Eliaslog.pw

In this little tutorial, I want to quickly note down how to implement Github Actions into a Github-Repo so I don’t forget. 😅

What are Github Actions?

To get an initial idea, what Github Actions are conceptually, have a look at the following chart:

./Unbenannt-2021-05-17-1735.png

In the beginning there’s always an event that takes place and triggers a workflow. This workflow contains one or more jobs that can be run simultaneously (but don’t have to!). Inside these jobs there can be multiple steps that are running sequentially.

You can implement multiple workflows in your project and listen for different events to trigger subsequent workflows and jobs.

Setting up a workflow

Let’s now transfer this to a real life scenario.

Say we want to implement a workflow that triggers after a pushed commit to the master branch of your repo (event). This workflow consists of one job that then gets the current code of your repo (first step), runs a build command (second step) and deploys the build project through ftp to a shared webspace (third step).

Let’s do it!

The Github Actions are living a special directory inside your source project named .github. Within that, we need an actions directory.

In this directory, the different workflows reside as .yml files.

These files can be named whatever, but I resort to naming them after the branches that they are triggered by.

So in master.yml, we first need to specify the event that triggers the workflow and a name for the workflow.

# .github/actions/master.yml
on:
  push:
    branches:
      - master
name: 🚀 Deploy website on push

It would be sufficient to just note down on: push resulting in a workflow that runs every time any branch receives a new push. To restrict when a workflow is run, we can however specify the activity type like shown above. To get an overview on all of accepted activity types, head over to the Github Actions Docs.

The configuration above triggers a workflow as soon as we receive a push of code on the master branch. The workflow that is triggered has the Name 🚀 Deploy website on push (yes, emojis work 🚀).

Setup Jobs & Steps

The jobs of our workflow are conveniently noted under jobs:

jobs:
  my-first-job:
    name: 🎉 Deploy
runs-on: ubuntu-latest

The id and the name of the job can be individually chosen. After that it’s mandatory to define the type of machine that the jobs run on. Usually ubuntu-latest or ubuntu-20.04 works for all node-related stuff but here’s an overview of all machines.

After that we define our steps that are handled by this machine.

jobs:
  my-first-job:
    name: 🎉 Deploy
runs-on: ubuntu-latest
steps:
  - name: 🚚 Get latest code
    uses: actions/checkout@v2

  - name: Use Node.js 12
    uses: actions/setup-node@v2-beta
    with:
      node-version: "14.17.0"

  - name: 🔨 Build Project
    run: |
      npm install
      npm run build

  - name: 📂 Sync files
    uses: SamKirkland/FTP-Deploy-Action@4.1.0
    with:
      server: ftp.server.de
      username: ${{ secrets.ftp_username }}
      password: ${{ secrets.ftp_password }}
      local-dir: ./dist/

Okay let’s break this down.

Every step has an individual name. In this instance we first want to get the latest code that has just been pushed to the repo. Github provides some predefined steps that are commonly used in Actions such as checking out the most recent code (list of predefined actions).

To get our current code we use actions/checkout@v2.

We can make use of these provided steps by simply referencing them in the property uses.

After we’ve received our latest code, in order to run npm commands, we need to set up a node environment. We do so with the actions/setup-node@v2-beta. To make sure everything works as expected, we have to indicate which version of node we want to use. To provide arguments for a given step we use jobs.<job_id>.steps[*].with where we can simple note key/value pairs that are avaible within the current step.

In the third step, we can now run our build process. As these steps are executed one after another, the latter steps have access to the outcome of the previous steps.

In this case, our project package.json has a defined build command, that we, after we’ve installed all node-packages with npm install , simply execute.

Using jobs.<job_id>.steps[*].run we have access to the operating system’s shell, in this case node.

After the build process is done, the last step is executed, where we deploy our resulting app via ftp. Sam Kirkland provides a handy predefined action for this: SamKirkland/FTP-Deploy-Action.

We provide four arguments for this action: server, username, password and local-dir.

To hide our sensitive information from public repos, like ftp-username and ftp-password, we use the build-in environmental variables.

Accessing the “settings” tab on the given repo, in the “secrets” section, we are able to define our “action secrets”. Saved there, they will be available within a secrets object. You can access this object in the yaml file like shown above.

Executing functions

With your first commit containing the .github/actions directory, your defined workflow will become visible in the “Actions” tab of your Github repository. As we pushed a commit, the event “on push” will be triggered and the running and finished task will be listed.

There’s a lot more to learn and see about Github Actions but I hope that this basic example gives you an idea of what Github Actions is capable of and how you can use it. It is, after all, a free pass to run code on Microsoft-backed servers, so it should definitely be of interest to any developer.

Full Code

# .github/actions/master.yml

on:
  push:
    branches:
      - master
name: 🚀 Deploy website on push
jobs:
  web-deploy:
    name: 🎉 Deploy
    runs-on: ubuntu-latest

    steps:
      - name: 🚚 Get latest code
        uses: actions/checkout@v2

      - name: Use Node.js 12
        uses: actions/setup-node@v2-beta
        with:
          node-version: "14.17.0"

      - name: 🔨 Build Project
        run: |
          npm install
          npm run build
      - name: 📂 Sync files
        uses: SamKirkland/FTP-Deploy-Action@4.1.0
        with:
          server: ftp.server.de
          username: ${{ secrets.ftp_username }}
          password: ${{ secrets.ftp_password }}
          local-dir: ./dist/
The creation of this post was made possible by coffee.
Buy me a coffee