Your guide to GitHub Actions in 5 steps 📚
Tags: github, beginners, tutorial, docker
Published: 2020-05-21 14:33:28

I've been fiddling around the new changes GitHub made this year at [Satellite Virtual 2020](https://githubsatellite.com/). There's a whole article on [GitHub Blog](https://github.blog/2020-05-06-new-from-satellite-2020-github-codespaces-github-discussions-securing-code-in-private-repositories-and-more/) 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](https://github.com/features/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)](https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment) 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](https://media.giphy.com/media/3osxY4WVmVocngv5Is/giphy.gif)
<figcaption>Just don't do these type of jumps 🥴</figcaption>

---

##### _⚠ We will be working with Dockerfiles in this tutorial. If you're new to this, I highly recommend [learning it first](https://docs.docker.com/get-started/).⚠_

## 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](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-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:

```dockerfile
FROM debian:9.5-slim

ADD entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
```
![Add Dockerfile](https://dev-to-uploads.s3.amazonaws.com/i/lknrhn0yt7q1r3q9dpuc.jpg)

We're fetching the [Debian image from Docker Hub](https://hub.docker.com/_/debian), creating a [_entrypoint_](https://hub.docker.com/r//entrypoint.sh) 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:

```shell

#!/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](https://dev-to-uploads.s3.amazonaws.com/i/07enojrxzleebysjux9w.jpg)

✨ **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](https://rollout.io/blog/yaml-tutorial-everything-you-need-get-started/).

✨ **Add the YAML file**: Create this new file under _actions/action.yml_ and add the following code:

```yml
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_:

```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`](https://developer.github.com/webhooks/event-payloads/#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`](https://github.com/actions/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](https://dev-to-uploads.s3.amazonaws.com/i/d9yiqb4d1nuszwm28d31.jpg)

✨ 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](https://dev-to-uploads.s3.amazonaws.com/i/g6yyd61efp5fzguv9z1v.jpg)

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.

---

<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Sound familiar? 😂<br>.<a href="https://twitter.com/hashtag/coding?src=hash&amp;ref_src=twsrc%5Etfw">#coding</a> <a href="https://twitter.com/hashtag/developer?src=hash&amp;ref_src=twsrc%5Etfw">#developer</a> <a href="https://twitter.com/hashtag/webdevelopment?src=hash&amp;ref_src=twsrc%5Etfw">#webdevelopment</a> <a href="https://twitter.com/hashtag/iosdevelopment?src=hash&amp;ref_src=twsrc%5Etfw">#iosdevelopment</a> <a href="https://twitter.com/hashtag/javadevelopment?src=hash&amp;ref_src=twsrc%5Etfw">#javadevelopment</a> <a href="https://twitter.com/hashtag/java?src=hash&amp;ref_src=twsrc%5Etfw">#java</a> <a href="https://twitter.com/hashtag/python?src=hash&amp;ref_src=twsrc%5Etfw">#python</a> <a href="https://twitter.com/hashtag/ruby?src=hash&amp;ref_src=twsrc%5Etfw">#ruby</a> <a href="https://twitter.com/hashtag/php?src=hash&amp;ref_src=twsrc%5Etfw">#php</a> <a href="https://twitter.com/hashtag/html?src=hash&amp;ref_src=twsrc%5Etfw">#html</a> <a href="https://twitter.com/hashtag/javascript?src=hash&amp;ref_src=twsrc%5Etfw">#javascript</a> <a href="https://twitter.com/hashtag/codingmeme?src=hash&amp;ref_src=twsrc%5Etfw">#codingmeme</a> <a href="https://twitter.com/hashtag/codingjoke?src=hash&amp;ref_src=twsrc%5Etfw">#codingjoke</a> <a href="https://twitter.com/hashtag/developerhumor?src=hash&amp;ref_src=twsrc%5Etfw">#developerhumor</a> <a href="https://twitter.com/hashtag/devhumor?src=hash&amp;ref_src=twsrc%5Etfw">#devhumor</a> <a href="https://twitter.com/hashtag/devhumour?src=hash&amp;ref_src=twsrc%5Etfw">#devhumour</a> <a href="https://twitter.com/hashtag/programmerhumor?src=hash&amp;ref_src=twsrc%5Etfw">#programmerhumor</a> <a href="https://twitter.com/hashtag/programmingmeme?src=hash&amp;ref_src=twsrc%5Etfw">#programmingmeme</a> <a href="https://twitter.com/hashtag/programmingjoke?src=hash&amp;ref_src=twsrc%5Etfw">#programmingjoke</a> <a href="https://twitter.com/hashtag/devlife?src=hash&amp;ref_src=twsrc%5Etfw">#devlife</a> <a href="https://twitter.com/hashtag/webdesign?src=hash&amp;ref_src=twsrc%5Etfw">#webdesign</a> <a href="https://t.co/zBRsXQ2pMi">pic.twitter.com/zBRsXQ2pMi</a></p>&mdash; Coding Interview Coach (@CoachCoding) <a href="https://twitter.com/CoachCoding/status/1264949407784603648?ref_src=twsrc%5Etfw">May 25, 2020</a></blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

---

#### [📫 Subscribe to my weekly developer newsletter 📫](https://mailchi.mp/f59beeac6b9b/devupdates)

##### 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](https://medium.com/@vaibhavkhulbe)'s my Medium profile.