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
To activate and get started create a folder
.github/workflows and start with your first Action, by creating a file
A standard workflow consists out of some pre-defined sections:
- name (optional)
- trigger (required)
- jobs (required)
Let's start by giving our workflow a name:
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.
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
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!
At the time of writing there's only a choice of different environments, but no choice of different hardware configurations.
Find the full list in the GitHub Actions reference.
There are 2 major steps which should be known. A GitHub Actions build step can be:
- a predefined
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.
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.
Got thoughts, feedback, improvements, suggestions, or comments?
Let me know @mike_penz