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
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 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.
on:[ push, create ]
Besides repository events, you can also trigger workflows via webhooks or schedules.
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
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
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.
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
**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
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 )
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.