GitHub Actions CI/CD - Getting Started

Read the introduction to GitHub Actions here.

GitHub Actions fully depends on GIT to host your source code in the repository. It does not offer a UI to configure like Jenkins does, and fully depends on *.yml files located in the .github/workflows. This follows the same structure like other well known files GitHub supports in the .github folder.

To activate and get started create a folder .github/workflows and start with your first Action, by creating a file ci.yml.

A standard workflow consists out of some pre-defined sections:

• name (optional)
• trigger (required)
• jobs (required)
  • steps

Name

Let's start by giving our workflow a name:

name: CI

This workflow name will show up in the list of your workflows if you click on Actions, but also appear under the name (commit name) in the list of all executed workflows.

Trigger

Every workflow requires triggers which indicate when the workflow will be executed. This trigger will result in the workflow being started and all of its jobs to be executed.

For most workflows the push (Runs your workflow when someone pushes to a repository branch, which triggers the push event.) and pull_request (Runs your workflow anytime the pull_request event occurs. More than one activity type triggers this event.) will be most relevant ones.

Most triggers also allow to specify the actual actions when to run the workflow even further, which gives a great amount of flexibility to build workflows for all sorts of events.

Let's define a basic trigger which will execute the workflow every single time we open a pull request, or update the pull request by pushing a new commit to it:

on: # trigger section
    pull_request: # trigger

To only execute the workflow when the pull request is opened add the activity type filter.

on: # trigger section
    pull_request: # trigger
        types: opened # activity type

Find a list of all trigger events and their documentation in the official GitHub Actions Reference

Jobs

The last and most important section of your workflow are the jobs. Each workflow can contain out of a 1-N number of jobs which will be executed when the trigger is fired.

Each job will get its own unique id (which is by default also used as its name), define where it is executed on (runs-on) and the steps which will be executed.

jobs: # jobs section called "build"
  build: # one job, with its id
    runs-on: ubuntu-latest # the system to execute the job on
    steps: # start the section defining your build steps 
      - name: Run a one-line script
        run: echo Hello, world!

runs-on

At the time of writing there's only a choice of different environments, but no choice of different hardware configurations.

• ubuntu-latest
• windows-latest
• macos-latest

Find the full list in the GitHub Actions reference.

Steps

There are 2 major steps which should be known. A GitHub Actions build step can be:

• a shell script
• a predefined Action (via uses) offered in the marketplace

It's important to be aware that only a small amount of actions are offered from GitHub officially. If working in a secure environment (private repo). It's highly recommend to prefer official or verified actions, as they should be secure in general.

You can identify verified actions via their checkmark icon in the marketplace.

If you'd love to use a 3rd party action regardless, it's always recommend to check-out the source code of the action, and specify the specific GIT hash to use

Write working workflow

Let's combine all sections from the article and write a complete working workflow.

name: CI
on:
    pull_request:
jobs:
    ci:
        name: Build
        runs-on: ubuntu-latest
        steps:
            # Checkout the project source
            - uses: actions/checkout@v2
            # Execute the projects build
            - name: Build
              run: ./gradlew clean build
            # Execute additional steps
            - name: Detekt
              run: ./gradlew detekt

And that's it, you have a workflow which will be executed every time you open a PR (or update the PR), checks out the projects source code from this PR, and runs the build, and executes static code analysis.

Conclusion

GitHub actions are very powerful and come with a very flexible syntax, offering you the power to build the workflows your project needs.

Adding a workflow *.yml file into your repository offers a very quick way to add a build to your project, without the need to ever leave GitHub.com, or leave the context of your project.

The trickiest part is to get used to the YML syntax and debug more complex workflows.

Feedback

Got thoughts, feedback, improvements, suggestions, or comments?

Let me know @mike_penz