Create a "hello world" composite action with input

In the world of software development, automating workflows has become an essential part of increasing efficiency and reducing manual errors. One of the most accessible ways to achieve this is through the creation of custom actions on platforms like GitHub Actions. These actions allow developers to automate their software build, test, and deployment processes directly within their GitHub repositories.

In this topic, you'll learn how to get started by creating a simple "hello world" action. This action will serve as a basic introduction to the mechanics of building, implementing, and publishing your own actions. You'll also discover how to test your action and consider security implications to ensure your workflows run smoothly and securely.

Setting up a GitHub repository for the action

Begin by creating a new public repository on GitHub. You can name the repository according to your action's purpose or follow a naming convention like hello-world-composite-action. Once your repository is ready, clone it to your local machine. This will allow you to develop and test your action locally. Use the following command in your terminal to clone the repository:

git clone https://github.com/your-username/hello-world-composite-action.git
cd hello-world-composite-action

Within your repository's directory, it's time to create the essential files for your action. For a basic "Hello World" action, let’s create two scripts: hello.sh and goodbye.sh. Start with the hello.sh script that greets the user:

echo "echo Hello from the action" > hello.sh

Now, create the goodbye.sh script that will provide a parting message:

echo "echo Goodbye" > goodbye.sh

It's essential to grant execution permissions to your new script to ensure it operates smoothly within the GitHub Actions environment:

chmod +x hello.sh
chmod +x goodbye.sh

With your scripts in place and executable, add them to your repository and commit the changes. This will stage the new files, save the changes with a descriptive commit message, and push them to your GitHub repository:

git add hello.sh goodbye.sh
git commit -m "Add hello and goodbye scripts"
git push

Creating your action's metadata file

To craft a GitHub Action, you must begin by creating an action.yml file. This metadata file outlines the essential details and the operational structure of your action. It defines inputs, outputs, and the sequence of operations that your action performs.

Start by constructing a file named action.yml at the root of your repository. In this file, you'll outline the details of your "Hello World" action as follows:

name: 'Hello World'
description: 'Greet someone'
inputs:
  who-to-greet:  # id of input
    description: 'Greet'
    required: true
    default: 'World'

runs:
  using: 'composite'
  steps:

    - name: Set GitHub Path
      run: echo "$GITHUB_ACTION_PATH" >> $GITHUB_PATH
      shell: bash
      env:
        GITHUB_ACTION_PATH: ${{ github.action_path }}

    - name: Run hello.sh
      run: hello.sh
      shell: bash

    - name: Set Greeting
      run: echo "Hello ${{ inputs.who-to-greet }}."
      shell: bash

    - name: Run goodbye.sh
      run: goodbye.sh
      shell: bash

In this YAML file, under the name and description, the inputs field defines the parameters that users can specify. In this case, who-to-greet is an input that your action will use to customize the greeting message.

The runs section describes how your action is executed. With using: 'composite', tells GitHub Actions that the action is a composite action consisting of multiple steps. The steps included are:

• Set GitHub Path: Adds the GitHub Action's path to the environment path, making it possible to execute scripts included in your action.

• Run hello.sh: Executes a script named hello.sh, which should be in the root directory of your action repository.

• Set Greeting: Echoes a greeting to the console using the user-provided who-to-greet input.

• Run goodbye.sh: Executes a script named goodbye.sh that could offer a closing message or perform cleanup tasks.

After defining your action in the action.yml file, it's time to add it to the repository and secure it with a commit:

git add action.yml
git commit -m "Add action metadata file"
git push

To finalize the creation process, tag your commit. Tags are important for versioning and help users to refer to specific snapshots of your action:

git tag -a -m "Description of this release" v1
git push --follow-tags

These steps register your action with GitHub, allowing it to be referenced and used in workflows. The tag you've created marks the first official version of your action, signaling its readiness for public use.

Testing out your newly created action

To verify that your GitHub Action functions as intended, it's wise to test it within a workflow on a fresh repository. This ensures that your action interacts correctly with the GitHub Actions environment from the perspective of an end user. Here's how you can set up a test:

First, create a new repository on GitHub to serve as your testing ground. This repository will be separate from the one that houses your action code.

Once the new repository is ready, navigate to it and create a workflow file. In the repository, go to the .github/workflows/ directory. If this directory doesn't exist, you'll need to create it. Within this directory, create a new file named main.yml and fill it with the following content:

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - uses: actions/checkout@v4
      - id: foo
        uses: <your-username>/hello-world-composite-action@v1
        with:
          who-to-greet: 'this is a message running in my first action'

Replace <your-username> with your actual GitHub username and ensure the uses line points to the correct version of your action. This workflow will run whenever a push is made to the repository. It includes three steps:

1. Checking out the code with actions/checkout@v4.

2. Running your custom "Hello World" action with the specified input.

After setting up the main.yml file, you need to commit and push it to the repository to trigger the action:

git add .github/workflows/main.yml
git commit -m "Set up workflow to test Hello World action"
git push origin main

Once the workflow file is pushed, any subsequent push to your repository will initiate the workflow. You can see the workflow execution results by going to the "Actions" tab in your testing repository. This tab will show you all the runs of your workflows. Select the latest run to view the details.

Conclusion

This topic has guided you through the essentials of creating a custom "hello world" action on GitHub. We started with the setup of your action's metadata file, which included the action's name, inputs, outputs, and execution steps. We then moved on to implementing the action's logic with a simple script, ensuring that it was tested and functioning as intended. Following that, we discussed how to incorporate your action into a workflow for testing.