Building and Publishing Your Own Custom GitHub Action: A Comprehensive Guide

ByNakamura

GitHub Actions have revolutionized the software development landscape, offering developers powerful tools to automate workflows and streamline processes. While the GitHub Marketplace boasts a vast array of pre-built actions, there are times when a custom solution is necessary to address specific needs. This comprehensive guide will walk you through the intricate process of creating, testing, and publishing your own GitHub Action, empowering you to contribute to the ever-growing ecosystem of development tools.

Understanding the Power of GitHub Actions

Before diving into the creation process, it's crucial to grasp the fundamental concepts and significance of GitHub Actions. These automated workflows, triggered by various repository events, have become indispensable in modern software development practices.

GitHub Actions enable developers to:

  • Automate the entire software development lifecycle
  • Implement robust continuous integration and continuous deployment (CI/CD) pipelines
  • Execute comprehensive test suites automatically
  • Deploy applications seamlessly across various environments
  • Perform code analysis, security scans, and much more

The true beauty of GitHub Actions lies in their flexibility and reusability. Once created, an action can be shared and utilized across multiple repositories, fostering consistency and saving valuable time for development teams worldwide.

Crafting Your Custom GitHub Action: A Detailed Walkthrough

Let's embark on a journey to create a custom GitHub Action, using a real-world example of building an action for SBOM (Software Bill of Materials) enrichment using a tool called Parlay. This practical approach will provide you with hands-on experience and insights into the development process.

Step 1: Defining Your Action's Blueprint

The foundation of any GitHub Action is the action.yml file. This YAML configuration serves as the blueprint for your action, defining its inputs, outputs, and execution environment. Let's examine a comprehensive action.yml for our Parlay action:

name: "Parlay GitHub Action"
description: "Enriches SBOM files using Parlay for enhanced software composition analysis"
author: "Your Name"
branding:
  icon: "shield"
  color: "gray-dark"
inputs:
  input_file_name:
    description: "Path to the input SBOM file for enrichment"
    required: true
  enricher:
    description: "The Parlay enricher to use (e.g., ecosystems, vulnerabilities)"
    required: true
    default: ecosystems
  output_file_name:
    description: "Desired path for the enriched SBOM output file"
    required: true
  parlay_version:
    description: "Version of Parlay to use"
    required: false
    default: "0.1.4"
outputs:
  output_file_path:
    description: "Full path to the enriched SBOM file"
  enrichment_summary:
    description: "Summary of the enrichment process"
runs:
  using: "docker"
  image: "Dockerfile"
  args:
    - ${{ inputs.input_file_name }}
    - ${{ inputs.enricher }}
    - ${{ inputs.output_file_name }}
    - ${{ inputs.parlay_version }}

This enhanced action.yml file now includes additional inputs and outputs, providing more flexibility and information to users of your action. The parlay_version input allows users to specify a particular version of Parlay, ensuring compatibility and reproducibility.

Step 2: Implementing Robust Business Logic

The core functionality of your action is implemented in a script. For our Parlay action, we'll use a Bash script named entrypoint.sh. This script will handle the execution of Parlay commands and provide detailed output:

#!/bin/bash

set -e

# Function to log messages with timestamps
log_message() {
    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1"
}

# Check if all required arguments are provided
if [ "$#" -lt 3 ]; then
    log_message "Error: Insufficient arguments provided"
    echo "Usage: $0 <input_file_name> <enricher> <output_file_name> [parlay_version]"
    exit 1
fi

# Extract arguments
INPUT_FILE_NAME=$1
ENRICHER=$2
OUTPUT_FILE_NAME=$3
PARLAY_VERSION=${4:-"0.1.4"}

log_message "Starting SBOM enrichment process"
log_message "Input file: $INPUT_FILE_NAME"
log_message "Enricher: $ENRICHER"
log_message "Output file: $OUTPUT_FILE_NAME"
log_message "Parlay version: $PARLAY_VERSION"

# Ensure Parlay is installed and at the correct version
if ! command -v parlay &> /dev/null; then
    log_message "Installing Parlay version $PARLAY_VERSION"
    wget "https://github.com/snyk/parlay/releases/download/v${PARLAY_VERSION}/parlay_Linux_x86_64.tar.gz"
    tar -xvf "parlay_Linux_x86_64.tar.gz"
    mv parlay /usr/bin/parlay
    rm "parlay_Linux_x86_64.tar.gz"
fi

# Construct and execute the Parlay command
log_message "Executing Parlay enrichment"
full_command="parlay $ENRICHER enrich $INPUT_FILE_NAME > $OUTPUT_FILE_NAME"
eval "$full_command"

# Check if the command was successful
if [ $? -eq 0 ]; then
    log_message "Enrichment completed successfully"
    
    # Generate enrichment summary
    components_count=$(jq '.components | length' "$OUTPUT_FILE_NAME")
    file_size=$(du -h "$OUTPUT_FILE_NAME" | cut -f1)
    
    echo "enrichment_summary<<EOF" >> $GITHUB_OUTPUT
    echo "Enrichment completed successfully" >> $GITHUB_OUTPUT
    echo "Components enriched: $components_count" >> $GITHUB_OUTPUT
    echo "Output file size: $file_size" >> $GITHUB_OUTPUT
    echo "EOF" >> $GITHUB_OUTPUT
    
    echo "output_file_path=$OUTPUT_FILE_NAME" >> $GITHUB_OUTPUT
else
    log_message "Error executing Parlay command"
    exit 1
fi

log_message "SBOM enrichment process completed"

This enhanced script includes error handling, detailed logging, and generates a summary of the enrichment process. It also ensures that the correct version of Parlay is installed, adding an extra layer of reliability to your action.

Step 3: Containerizing Your Action for Portability

To ensure your action runs consistently across different environments, we'll package it in a Docker container. Create a Dockerfile with the following contents:

FROM alpine:3.14

RUN apk add --no-cache bash wget jq

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

This Dockerfile sets up a lightweight Alpine Linux environment, installs necessary dependencies, and prepares your entrypoint.sh script to run when the container starts.

Step 4: Rigorous Testing of Your Action

Testing is crucial to ensure your action functions correctly under various scenarios. Create a workflow file named .github/workflows/test.yml to automatically test your action:

name: Test Parlay Action

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test_action:
    runs-on: ubuntu-latest
    name: Test Parlay Action
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Run Parlay Action
        uses: ./
        with:
          input_file_name: ./test/sample-sbom.json
          enricher: ecosystems
          output_file_name: enriched-sbom.json
          parlay_version: "0.1.4"

      - name: Check Output
        run: |
          echo "Enriched SBOM content:"
          cat enriched-sbom.json
          
          echo "Enrichment summary:"
          echo "${{ steps.parlay.outputs.enrichment_summary }}"
          
          echo "Output file path: ${{ steps.parlay.outputs.output_file_path }}"

      - name: Validate SBOM
        run: |
          if jq empty enriched-sbom.json; then
            echo "Enriched SBOM is valid JSON"
          else
            echo "Error: Enriched SBOM is not valid JSON"
            exit 1
          fi

This workflow tests your action on every push and pull request, ensuring it functions correctly before any changes are merged.

Step 5: Publishing Your Action to the GitHub Marketplace

Once your action is thoroughly tested and working as expected, it's time to share it with the world by publishing it to the GitHub Marketplace. Follow these steps:

  1. Ensure your repository is public and contains all necessary files (action.yml, entrypoint.sh, Dockerfile, and any additional resources).
  2. Navigate to your repository on GitHub and click on the "Releases" tab.
  3. Click "Draft a new release" to create a new version of your action.
  4. Tag your release using semantic versioning (e.g., v1.0.0).
  5. Provide a detailed title and description for your release, highlighting key features and any changes from previous versions.
  6. Check the box that says "Publish this Action to the GitHub Marketplace".
  7. Fill out the required information about your action, including a detailed description, primary category, and any relevant screenshots or videos.
  8. Review the marketplace agreement and click "Publish release".

Your action is now live in the GitHub Marketplace, ready for developers around the world to discover and use in their projects!

Best Practices for Developing GitHub Actions

As you continue to refine and expand your custom action, keep these best practices in mind:

  1. Version Control: Adhere to semantic versioning principles for your releases, allowing users to easily understand the impact of updates.

  2. Comprehensive Documentation: Provide clear, detailed documentation on how to use your action. Include examples, parameter descriptions, and any prerequisites.

  3. Security Considerations: Be mindful of security implications, especially if your action handles sensitive data. Regularly update dependencies and use GitHub's code scanning tools.

  4. Extensive Testing: Implement a robust testing strategy, covering various scenarios and edge cases. Consider using GitHub's matrix strategy to test across multiple operating systems and configurations.

  5. Performance Optimization: Optimize your action for speed and resource usage. Consider using composite actions for complex workflows to improve performance.

  6. Continuous Maintenance: Regularly update your action to fix bugs, add new features, and maintain compatibility with the latest GitHub Actions runner environments.

  7. Community Engagement: Encourage feedback and contributions from the community. Respond to issues and pull requests promptly to foster an active ecosystem around your action.

Conclusion: Empowering the Developer Community

Creating a custom GitHub Action is more than just automating a workflow; it's about contributing to the collective knowledge and efficiency of the global developer community. By following this comprehensive guide, you've not only learned how to create, test, and publish your own action but also gained insights into the philosophy behind effective action development.

As you continue to refine your Parlay SBOM enrichment action and potentially develop new actions, remember that each contribution, no matter how small, has the potential to significantly impact the way developers work. Your custom action could be the missing piece that streamlines a critical process for countless projects worldwide.

The world of GitHub Actions is ever-evolving, with new features and capabilities being added regularly. Stay curious, keep experimenting, and don't hesitate to push the boundaries of what's possible. Your innovative approach to solving problems through custom actions could inspire others and drive the entire ecosystem forward.

Happy coding, and may your custom actions make the development world a more efficient, secure, and collaborative place for everyone!

Similar Posts