loading...
Cover image for Your guide to GitHub Actions in 5 steps 📚

Your guide to GitHub Actions in 5 steps 📚

vaibhavkhulbe profile image Vaibhav Khulbe Updated on ・7 min read

I've been fiddling around the new changes GitHub made this year at Satellite Virtual 2020. There's a whole article on GitHub Blog about what they announced, like GitHub Discussions, Codespaces etc. While attending the event I was reminded of what they announced last year. One of the biggest announcement was the introduction of GitHub Actions!

As always, I started working on a repo which includes some very basic Actions just to test things out, and I was really impressed by its capabilities. Some of you might be using them in your projects but for those who heard this term for the very first time or want to dive into this topic, here's what all I have to tell you about GitHub Actions. ▶


Quick introduction to GitHub Actions ▶

In a sentence,

GitHub Actions is an automation service which enables you to create a custom Software Development Life Cycle (SDLC) directly in your GitHub repository (repo).

In a few sentences,

Actions are just some individual tasks which you provide to GitHub, and what it does is that it automates those tasks in your workflow. You set up these automated workflows in the same repo to build, deploy, test and release the code.

If you're into making workflows while working on your open-source project on GitHub while collaborating with Pull Requests (PR) and Issues, then Actions are a really nice and useful addition to your software and team.

There's no limit to how much Actions are useful. They're mostly used to make end-to-end Continous Integration/Continous Delivery (CI/CD) integrations and it works like a charm! ✨

Okay, looks like you're ready to make your first GitHub Actions. Leave the wait and jump along with me!

Jump fail GIF

Just don't do these type of jumps 🥴

⚠ We will be working with Dockerfiles in this tutorial. If you're new to this, I highly recommend learning it first.⚠

STEP 1: CREATE A DOCKERFILE

We will be doing this from scratch, without any templates. For that, after you're ready with your GitHub repo, the first thing you do is create a Dockerfile.

  1. Create a new branch: Let's call our branch first-action.

  2. Create a Dockerfile: Switch to first-action if you haven't already. Inside this make a directory called actions. Under this, create a file titled Dockerfile.

  3. Write the Docker code: We write the following code:

FROM debian:9.5-slim

ADD entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

Add Dockerfile

We're fetching the Debian image from Docker Hub, creating a entrypoint bash script where we will write more code regarding what the Action will actually do.

✨ Commit your file and open a PR against the master branch.

STEP 2: CREATE THE 'entrypoint'

Here we'll write the code of what we need to do with our Action i.e. output our name in a string. Yes, it's basic but this is just us starting with Actions, remember the capabilities are endless!

✨ Write the .sh code. Inside the same branch, the same folder we write the following code:


#!/bin/sh -l

sh -c "echo Hello everyone, I'm $INPUT_MY_NAME and this is my first GitHub Action!"

As you can see, we made an environment variable called MY_NAME wherein our name will be added dynamically just like we do it in other programming languages!

Creating shell script

✨ Commit and push your changes.

STEP 3: WRITE THE ACTION METADATA

All Actions need a metadata file which defines the inputs, outputs and main entrypoint for your action. This is written in the YAML (.yml) syntax.

✨ Add the YAML file: Create this new file under actions/action.yml and add the following code:

name: "Hello World!"
description: "Greet the world"
author: "Vaibhav Khulbe"

inputs:
  MY_NAME:
    description: "Who to greet"
    required: true
    default: "World"

runs:
  using: "docker"
  image: "Dockerfile"

Just like all other metadata files this one is also straightforward and tells GitHub Actions about the general information like author name, Docker image used and of course, the inputs.

✨ You know what to do next...commit and push the changes!

STEP 4: KICKSTART THE WORKFLOW

In this step, we will create and trigger the workflow. Workflows trigger based on any event you write. In our case, we can simply push the event.

  1. Create the main workflow file: All the workflow code lives under the .github folder. We make another folder workflows inside which we create the main.yml file.

NOTE: It's important to make this file directly under .github/workflows/ directory.

Here's the code for main.yml:

name: A workflow for my first GitHub Action
on: push
jobs:
  build:
    name: My first Hello World action
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: ./actions
        with:
          MY_NAME: "Vaibhav"

Let me explain it to you:

  • name: It simply gives your workflow a 'name'. This will appear in your PR if you visit the Actions tab in your repo.

  • on: It indicates that your workflow will execute anytime code is pushed to your repository. This uses GitHub's push event.

  • jobs: It is the base component of a workflow run.

  • build: It is an identifier from which we attach the job.

  • name: The job name. Easy, eh? ¯(°_o)/¯

  • steps: Here we define the series of different operations which constitutes the job.

  • uses: This uses a community-developed Action called checkout to allow the workflow to access the contents of the repo.

  • uses: It simply tells in which path we have the code for our Action.

  • with: This tells you about the input variables available in the Action. For us, it's the MY_NAME variable which is assigned the String value of "Vaibhav".

Action workflow main file

✨ Ahem, so what you always do in the end. 👀 (Start committing and pushing for the last time!)

And BOOM! Your action has been triggered! 🥳

But what does this Action do? I'm still confused!

Okay, anytime you make a new commit to the repo, the workflow will trigger.

The status of your Action is shown under the "Actions" tab in your repository. From there you will see the actions that have run, and you can click on the action's "Log" link to view details.

This is what you'll see there:

Final result

If things went well, you should see the string "Hello world my name is Vaibhav!" printed at the bottom as shown above.

STEP 5: MERGE IT!

Finally, we can incorporate the workflow by merging the current PR. Remember we're still in the first-action branch? To make sure your next commit or other commits from your contributors uses the current Action, we need to do this merge with the master branch.

✨ As the very last step, simply merge the opened PR and delete the first-action branch.



📫 Subscribe to my weekly developer newsletter 📫

PS: From this year, I've decided to write here on DEV Community. Previously, I wrote on Medium. If anyone wants to take a look at my articles, here's my Medium profile.

Posted on May 21 by:

vaibhavkhulbe profile

Vaibhav Khulbe

@vaibhavkhulbe

Web developer/designer | Freelance writer ✍️

Discussion

markdown guide
 

Well, that took some of the mystery out of things, thanks! It was pure Sorcery before! Cheers!

 

I'm glad you liked it! :)