How to create GitHub actions with attributes

In this post, I am going to talk about GitHub action attributes, and how to incorporate these attributes in a workflow file. If you are reading this post for the first time, I encourage you to read this post first on an overview of GitHub Actions.

Common Attributes in GitHub Actions

name

You can have a name for your workflow or steps although it is not required. However, it is good practice to have it since it is helpful in debugging.

on

on is a key or attribute that lists events that trigger the workflow. This attribute is required for every workflow file. If there are more than one events that trigger a workflow, you need to specify those events in brackets. You also have more control over triggering workflow with event activity types, filters, and conditionals. I will talk about event activity types and filters in another post later.

single event	on: push
multiple events	on:[ push, create ]

Besides repository events, you can also trigger workflows via webhooks or schedules.

jobs

The jobs is an attribute that describes all the jobs running in the Workflow file. A Workflow must have a minimum of one job. Each job must be a unique identifier that must start with a letter/ underscore. They should contain only alphanumeric characters, -, or _.

jobs:
    myjob:
      #whatever myjob does comes here
    anotherjob:
      #whatever anotherjob does comes here

runs-on

specifies the virtual machine ( OS ) that jobs execute on. These virtual machines are called runners. You can specify these runners in YAML format as ubuntu-latest ( or ubuntu-22.04 ), windows-latest ( or windows-2022 ), and macos-latest ( or macos-11 ). A full list of runners can be found on GitHub documentation on runners.

In addition, you can specify self-hosted runners for more control of the hardware, operating system, and software you used in the virtual machines.

steps

Each job consists of one or more steps. A step can be an action and/ or a shell script command. Each step runs sequentially in its own process in the virtual environment. However, you can share data from one step to another. GitHub also provides built-on steps for jobs. Although it is not required, you can specify a name for each step just as you can do it for jobs.

name: Greetings
on: push
jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        run:  echo “Hello readers”

How to bundle everything together

Now that we have a basic understanding of attributes, let's see how to create a workflow file from scratch.

We are going to create a Workflow file from scratch. You can use any text editor of your choice. However, I am going to use the web editor on GitHub. One advantage of using this editor is it checks YAML syntax errors on the go.

We are going to do a simple task on ubuntu. We will be creating a directory and creating files inside that directory and displaying the content of the directory.

Adding actions with "uses" attribute

If you have a complex job that needs more than one or two steps. You will need more than one shell script/command for each step to accomplish this task. If you write your own script, you will need more time to write and test your code. This is why it is important to use actions, which are tested blocks of code for complex and frequently repeated tasks.

You can use uses attributes to add actions to steps by specifying the location of the action.

An action can be in 3 locations

Same repository as your workflow file
public repository
Docker container

**Note: You can create custom actions and reference those in your workflow file. Creating custom action is beyond the scope of this post. I will be discussing this in a later article.

name: example-action
on: [push]
jobs:
  sampleActions:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v3 #checkout this code to your runner

Job dependencies with "needs" attribute

Jobs, by default, run in parallel. However, you can make jobs run one after another, in case you need, by creating dependencies. The needs attribute is used to create these job dependencies.

Jobs
    Job1:
    Job2:
    Job3:
         needs:[job1,job2]

In this case, job3 will not run until job1 and job2 complete their tasks.

Adding Conditionals with "if"

You can add conditionals in GitHub Action to control the flow of execution. One such conditional is if.

if prevents running a job if the condition specified is not satisfied. The job will be skipped.

name: conditionals
on: [push,create]
jobs:
  printPush:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps: 
      - name: print_push_event
        run: echo "this is push event"
  printCreate:
     if: github.event_name == 'create'
     runs-on: ubuntu-latest
     steps: 
      - name: print_create_event
        run: echo "Did you create a branch/tag ?"

In the above example, there are two jobs. The first job runs only on the push event; the second one on creating an event( that is when you create a branch or tag )

You can also add conditionals for the "on" attribute to control the triggering of the workflow file. I will more about such conditionals later when I talk about filters and event activity types.

Conclusion

In this post, you learned the common attributes used in GitHub Actions, creating a workflow file, job dependencies, and controlling the flow of execution with the if condition. If you are reading this post for the first time, I will recommend reading my first post on GitHub Actions. It is an overview of GitHub Actions. In my next articles, I will be discussing artifacts, environment variables, and more conditionals.

Daminda Dinesh