A Beginner's Guide to Github Actions

In this article, we will be diving into the world of GitHub Actions, exploring the basics of this powerful automation tool. Whether you are a beginner or an experienced developer, you will find that GitHub Actions is a valuable tool to have in your arsenal.

What is GitHub Actions?

GitHub Actions is a feature provided by GitHub that allows users to automate their software development workflows, including building, testing, and deploying code. With GitHub Actions, you can create custom automated processes that run whenever specific events occur in a GitHub repository. For example, you can configure a workflow that automatically builds and deploys your code whenever you push changes to a specific branch.

So, after this brief explanation, let's jump to the GitHub Actions features.

Workflow Files

A workflow file specifies the steps that should be taken to automate any task, like building, testing, and deploying your code or even sending an sms when someone opens a pull request.

The workflow files are composed of Events, Jobs, Runners, Steps and Actions.

Events

Events are the triggers for the workflow, they are what needs to happen for this workflow to fire and run the automated work.
Events are defined in the yaml workflow file by passing the on property.

Examples of events:

• PR Created
• Push
• Issue Created
• Collaborator Join
• PR Merged

And you can specify branches, statuses, tags and paths to specifically limit the trigger to the desired event.

I recommend reading the documentation to know all existing events.

Jobs

Jobs group a set of steps that will be executed. After the Worflow is triggered, it will run all the jobs presented on it.
Inside the job we need to specified the runs-on property, that correspond to the enviroment this job will run, most commom is ubuntu-latest.

Steps

Each step in a job represents a single task that should be performed. The steps can be defined using either an action or a command-line command.

An action is called using the uses property, and its parameters are passed to the action through the with property. Alternatively, a command-line command can be executed using the run property.

Heres an example of an workflow.yaml file:

name: Test Workflow 

on:
  push: # Push event
    branches: # On branches 
      - 'releases/**'
      - 'master'

jobs:
  hello_world: # Define the job
    runs-on: ubuntu-latest # Specify the runner to run the job on
    name: Lint code
    steps:
      - name: Run Linter
        uses: github/super-linter@v3 # Use Github Super Linter repository
        with: # Input fot the action
          some_api_key: ${{ secrets.api_key }} # Get the API key from repository secrets
      - name: Print IPv4 # Some random command
        run: ifconfig -a # Run ifconfig command

⚠️ In order for your Workflow file to work correctly, it needs to be placed inside the /.github/workflows path within your repository.

-root
  -.github
    -workflows
     your_worflow_file.yaml

Once you've set up a workflow file within your repository, there's nothing left to do but code!

Actions Files

The actions are a pre-packaged set of instructions that perform a specific task. Whether you create your own custom actions or use actions from the GitHub Actions Marketplace, you can easily integrate them into your workflows using YAML files.

Actions are defined in a action.yaml file and must be stored in the root directory of your repository. It is recommended to store actions that will be used by third-parties or across multiple projects in a separate, dedicated repository that is publicly accessible. This ensures that the action is easily accessible and reusable by others.

Actions files are formed by name, description, inputs and runner.

Inputs

The inputs section defines the data needed to perform this action, which must be provided in the workflow that invokes them as mentioned earlier.

Runs

The runs section specifies the runtime environment for the action (example: Node.js version 12), and the main entry point for the action (example: dist/index.js).

Here´s an example:

name: "My Custom Action"
description: "A custom action for doing something cool."
inputs:
  input1:
    description: "The first input for the action."
    required: true
  input2:
    description: "The second input for the action."
    required: false
  input3:
    description: "The third input for the action."
    required: false
  ...

runs:
  using: "node12"
  main: "dist/index.js"

Main file

The main file used in an action is typically a script file that is executed when the action is triggered in a workflow. The script file can be written in a variety of programming languages, such as JavaScript, Python, or Ruby.

Here is an example of a JavaScript script that could be used as the main file in an action:

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

async function run() {
  try {
    const command = core.getInput('command');
    console.log(`Running command: ${command}`);

    await exec.exec(command);
  } catch (error) {
    core.setFailed(error.message);
  }
}

run();

Note that i used the @actions/core and @actions/exec, these libraries are part of the GitHub Actions Toolkit, a collection of libraries and tools provided by GitHub to simplify the development of custom actions for GitHub Actions.

The actual implementation of your main file will depend on the requirements of your action and the tools and services that you are integrating with.

Illustration

To summarize, I found this image on the internet that excellently illustrates the hierarchy within GitHub Actions, showing all the components discussed and their interrelationships. It serves as a visual representation of the concepts covered in this article and I believe it can help to better visualize how it works.

Thank you for reading this far and I hope it helped you understand a little more about this incredible feature on GitHub! 😊