Creating GitHub Actions for community engagement

By Cristian Matos Richards

In this article we learn:

What are GitHub actions

What are workflows

What is a CI/CD Pipeline?

How to install actions

Great actions for improving collaboration

How to configure an action's metadata

How to structure a YAML file

How to create an action with JavaScript

what are GitHub actions

GitHub Actions actions are tasks that can be executed in the workflows that we define in our project. There are multiple actions in the GitHub Marketplace that can be used, such as those that allow you to upload and download artifacts from other projects such as jobs and packages. On top of all that, we can also develop our actions to use in our project or make them public so that other developers can use them.

What are workflows

According to the docs, "A workflow is a configurable automated process, authored in YAML and running one or more jobs." For example, in open-source projects, which often receive new updates and contributors, the number of tasks needed can become overwhelming depending on the number of contributors working on the project. That's where workflows, such as on CI/CD pipelines, can benefit from having actions delegating and lowering the number of repetitive tasks done manually to keep the project running smoothly.

What is CI/CD Pipeline?

These are the common steps of the development lifecycle, CI means Continuous Integration and CD means Continuous Delivery.

Introduction

While volunteering for the Equity Cohort program, I got the opportunity to learn and become familiar with GitHub actions. Before this opportunity, I had never tried creating an action and was only vaguely aware of them. I mostly noticed them in "action" when I saw a neat message after I committed code on GitHub 😅. Creating one wasn't as simple as I would have thought. But their benefits, specifically when collaborating with a team, make them all the more worthwhile to learn about and implement.

How to install actions

GitHub Marketplace provides solutions for streamlining your workflow. Knowing the distinct features and advantages of each action will enable you to choose the ideal tool for the job installing actions in GitHub is simple:

1. Find the action you want on the GitHub Marketplace.
2. Read the Marketplace page to check for prerequisites.
3. Click Use latest version in the top right (or select an older version if you need).
4. Copy the code from the pop-up, paste it into your repository’s workflow YAML file, and save.
5. Make sure you read the action’s documentation to check for any extra setup and how to use the action.

Suggestions

Great actions for improving collaboration

Twitter, Together!: A GitHub action to tweet from a repository.
Post Slack Messages: GitHub Action for posting Slack messages.
GitHub Tag Action: A GitHub Action to tag a repo on merge.
Assign Reviewers To Assignees: GitHub Action that assigns reviewers based on assignees.
GitHub Sync: This action helps you to sync your PRs with tasks in Teamwork to streamline team collaboration and your development workflows.
Issue Action: GitHub action for GitHub issue.
First Interaction: An action for filtering pull requests and issues from first-time contributors.

Creating an action

Creating actions can be an overwhelming task, so to help you on your journey, here are two indispensable resources that can assist you in getting started; Actions Toolkit and Javascript action template. Still, this article will dive into how to create an action.

Configure action metadata

To configure the metadata for a GitHub Action, you'll need to create an action.yml file in the root directory of your Action repository. The file should have a .yml or .yaml file extension and should include information about your Action, such as its inputs, outputs, and main entry point for your action, written in YAML syntax.

What is YAML

YAML is a data serialization language commonly used in configuration file creation. This emphasizes that YAML is for data rather than documents, YAML stands for "yet another markup language" or "YAML ain't markup language" (a recursive acronym).

YAML is a popular computer language because it is human-readable and easy to understand. Additionally, other programming languages can use this format because it is accessible and adaptable. The primary advantage of using YAML is its readability and writability. YAML is the format to use if you need a configuration file to be simpler for people to read. JSON and XML both have their uses, so YAML is not a total replacement.

YAML also supports various data types, including cases, arrays, dictionaries, lists, and scalars. It supports the majority of popular programming languages, including JavaScript, Python, Ruby, etc.

How to structure your YAML file

Once we have the file created, we must begin to configure it with the YAML syntax. These are some of the parameters that can or should be configured:

name: 'mandatory, it is the name that we want to give to the action.'
author: 'Optional, the name of the author.'
description: 'Mandatory, it is the description of the parameter.'

inputs: 'Optional, it is used to define the input parameters 'that our' action will have. This will allow the workflow to configure the behavior of the action depending on the values passed to it.'

  input_1: 'The name of the input , which will be the identifier that is then used to get the input value. This value is written directly, it is not preceded by any label (it will be seen later in an example)'
    description: 'mandatory, it is the description of the parameter.'
    required: 'required, a Boolean indicating whether the user of the action is required to specify a parameter.'
    default:' optional, it is a value that the input will have by default if the user does not specify any when using the action.'
  input_2: 
    description: This is the second input parameter.
    required: 'required, a Boolean indicating whether the user of the action is required to specify a parameter.''
    default: another default value

runs: 'Mandatory, indicates that it begins to specify how the action is going to be executed. The rest of the values have a higher level of tabulation.'
  main: ' Required, the file containing the action code.'
    ...

outputs: 'optional, used to define the values that the action will return. They are normally used to return the result of an operation or request. This output data can be used later in the workflow. '
  output_1: 'which will be the identifier in which the data is then left. This value is written directly, it is not preceded by any label (it will be seen later in an example). '
    description: 'This is the first output parameter. [mandatory, it is the description of the output parameter.]'
  output_2:
    description: 'This is the second output parameter. [mandatory, it is the description of the output parameter'

In the end your YAML file should end up looking similar to this one

name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'node16'
  main: 'index.js'

These parameters are the ones needed to define an action with GitHub Actions. In addition to these, other parameters must also be defined so that the action knows how to execute the JavaScript application or the Docker container. Still, these parameters will be seen in the section for each.

You can also configure the branding to put an icon to our action and that it is displayed with it. The parameters are:

• branding : it does not proceed from anything, this label is necessary to begin to define the icon. The following labels have one more level of tabulation:
• icon : the name of the icon we want to put from the Icônes library ( https://icones.js.org/ )
• color : the color that we want to put on our branding. Options are: white, yellow, blue, green, orange, red, purple, or gray-dark.

Create an action with JavaScript

To create an action using JavaScript, we have to configure the action file to conform to this type of language. This type of action makes use of Node.js to be able to package the project and install the dependencies that the project has and always be able to test it in the same environment.

Therefore, our project will have a package.json file that will be in charge of registering the packages that we use. This is important since we will need to include packages in the project that will allow us to connect with the flow of actions to, for example, obtain the input variables and write to the output one.

The first step is to create the metadata file, therefore, let's see the elements that can be added:

• runs : mandatory, indicates that it begins to specify how the action is going to be executed. The rest of the values have a higher level of tabulation.
• using : Required, the runtime used to execute the code specified in main (node12 or node16).
• main : Required, the file containing the action code.
• pre : optional, Pre runs at the start of the job (before the steps are executed) and is typically used for setup. This parameter will not be configured in this project. It would be specified as pre : 'pre.js' .
• pre-if : optional, add a condition for the pre code to be executed. This parameter will not be configured in this project. It would be specified as pre-if : 'runner.os == linux' .
• post : optional, Post runs at the end of the job, after the last step has executed. This parameter will not be configured in this project. It would be specified as post :'post.js' .
• post-if : optional, adds a condition for the post code to be executed. This parameter will not be configured in this project. It would be specified as post-if : 'runner.os == linux' .

We will create the file action.yml in the path . github / actions / js - repeat , where we will also include the rest of the files. The content of the metadata file is as follows:

name: 'My Action'
description: 'This is my Action'
inputs:
  name: 'input_name'
  description: 'A description of the input'
outputs:
  name: 'output_name'
  description: 'A description of the output'
runs:
  using: 'node12'
  main: 'index.js'

Steps

Create a public GitHub repository that holds your action, even if you're the only one that will use it. Name the repo based on what the action will do. it is entirely up to you.

Make sure to add a README file and a .gitignore template based on Node from the dropdown menu, then choose the license (preferably MIT).

Before you clone the GitHub repository, create or go to the folder/directory in your local repository where you want to store the action. To clone the GitHub repository into that folder, click the green code button and copy the SSH link into your terminal line this:

>git clone [e-mail]:rcmtcristian/HelloYou.git
Cloning into 'HelloYou'...
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (5/5), done.
Receiving objects: 100% (5/5), done.
remote: Total 5 (delta 0), reused 0 (delta 0), pack-reused 0

Tip: to skip some of the templating you can type -y to accept all the default options
Extra Tip: To open the terminal in the folder, Type cmdinto the location bar at the top of the window and tap enter

Creating a new file

In the folder/directory create a new file called index.js and open it in your text editor. In this file you would import the node module @action/core here at the top of the file:

const core = require('@actions/core');

As well as define the JavaScript code that will run when the action is executed. Here is a simple example of what this code might look like:

async function run() {
  try {
    const name = core.getInput('name');
    console.log(`Hello ${name}!`);
  } catch (error) {
    core.setFailed(error.message);
  }
}

run();

Installing dependencies
Next, you will need to create a package.json file in the same directory. This file specifies the dependencies that the action requires, as well as some other metadata about the action.

Here is an example of what the package.json file might look like:

{
  "name": "hello-world-javascript-action",
  "version": "1.0.0",
  "dependencies": {
    "@actions/core": "^1.0.0"
  }
}

Once you have created the index.js file and the package.json file, you can run the npm install command to install the necessary dependencies.

Tip: Setting up the @actions/core dependencies is essential, it functions for setting results, logging, registering secrets and exporting variables across actions

With these changes, we can push to the repository to see how the actions are executed.

Publish our action on GitHub Marketplace

We may publish actions we create on GitHub Marketplace, making them discoverable by other developers. It is advised that you construct the action in your repository so that it can be readily identified and utilized by third parties; this implies that all action files, such as the actions, must be stored in your repository. yml, it will be in the root of the repository. The exception is if you have several related actions that need to be updated together for them to work correctly, then you can put them in a repository together (with each in a separate folder and an action.yml in each folder)

We have done it!!!!

Now that you know how to create your own GitHub Actions, why not give it a try? Head to the GitHub Marketplace and start exploring the existing Actions, or create your own and share it with the community. With GitHub Actions, the possibilities are endless, so start building and see what you can accomplish