My gh-actions playground

Small examples of interesting GitHub actions combinations.

How to run this playground

Most workflows where intentionally left with workflow_dispatch so they don't run by accident on every commit. Not as if it was a big issue, since they do mostly nothing by design.

But you can also run them using the act command line tool, which emulates the GitHub actions environment in a quite near the real thing way.

So, the three big ways to run a workflow:

• Visit the actions page and run them by hand
• Use the GitHub CLI: gh workflow run .github/workflow/00-hello-world.yml
• Use act: act -W .github/workflows/00-hello-world.yml

Overview

GitHub Actions is what happens when yaml and bash decide to have a child.

The workflow files are used to common integration routines: run tests, check the quality of code, perform any chore that can be automatized, scripted.

Workflow file syntax

Each workflow file must define:

• name (unique across all workflows)
• on (event)
• jobs (actual work)

Events

What could possibly trigger an workflow?

• You hit a button
• A git push or something
• Another workflow

More possibilities here.

Jobs

• Give cool names to your jobs, not just build
• One workflow can house several jobs
• Jobs will run in parallel unless you do something about it
  • make jobs needs other jobs

More details here.

00 - smallest possible

• Manual dispatch
• Echoes 'hello world'

01 - occurs on every git push or merge

• The 101 of CI
• Echoes 'hello word from some branch'

02 - have two jobs

• Remember, runs in parallel!
• Pretty much like two distinct workflows, but sharing rent of a workflow file

03 - have two jobs but in sequence

• Make sure the second needs the first

04 - make one job use another workflow

• This is why workflow_call exists
• Don't misread as workflow_dispatch, it's another thing
• Quite similar to what we do when consuming actions from marketplace

05 - jobs inputs

• Both workflow_call and workflow_dispatch can receive inputs
• Use inputs inside the steps inside jobs

06 - jobs outputs

• You can define outputs values so other jobs can check on
• For dynamic outputs check the $GITHUB_OUTPUT variable usage

07 - environment variables

• The repository itself can contribute with custom variables
• Use GitHub CLI to list, set or remove repository variables
• If using act, create a .vars file to define variables
• With act there is also a .env file but we talk about it later

# ~/github/gh-actions-playground/.vars
X="some value from vars"

08 - secrets

• Very useful to interact with the world outside the repo
• Define secrets via web console settings
• Or use GitHub CLI to create them, pretty handy!
• With act, just put it inside a .secrets file!
• Note: secret values are not echoed on logs

# ~/github/gh-actions-playground/.secrets
X=10
MY_SECRET="not telling you!"

[sombriks@thanatos gh-actions-playground](main)$ gh secret set X
? Paste your secret **

✓ Set Actions secret X for sombriks/gh-actions-playground

09 - steps

• Simplest step is a run command
• Complex ones uses external actions from marketplace
• Give proper names for your steps

More details of what is possible here

10 / 11 - define outputs for reusable workflows

• Define a reusable workflow with an output section
• Define a workflow with a job consuming the reusable

More info here and here.

Noteworthy 3rd party actions

• This is why GitHub Actions it's better than other CI tools from other vendors

• Rich ecosystem

• Java

• Node

• Docker

• AWS Actions

• Upload

• Download

• Checkout

There's much, much more!

Writing good CI/CD pipelines

• Run tests
• Publish packages or images
• For GitOps, update desired state on IaC manifests files

Conclusion

This playground is intended to be simple, educational.

It's up to you combine the techniques sampled here to build real things.