github-actions-fun

This is a collection of GitHub Actions examples along with notes and references.

To limit the number of GitHub Actions minutes consumed, I've included a simple try_workflow.sh script that copies only one workflow file to the .github/workflow directory for execution and clears out any old workflow files.

1. Shell Commands with run:

./try_workflow.sh workflows/01_hello.yml

• Status:
• Workflow: 01_hello.yml
• Reference: jobs.<job_id>.steps[*].run
• A simple workflow that demonstrates the run: statement to execute shell commands
• Example runs in bash, python, and powershell using both ubuntu and windows

2. Executing Actions with uses:

./try_workflow.sh workflows/02_actions.yml

• Status:
• Workflow: 02_actions.yml
• Reference: jobs.<job_id>.steps[*].uses
• A workflow that demonstrates the uses: statement to execute a GitHub Action
• Publically available GitHub Actions may be found in the Actions Marketplace

3. Serializing dependent jobs with needs:

./try_workflow.sh workflows/03_needs.yml

• Status:
• Workflow: 03_needs.yml
• References:
  • jobs.<job_id>.needs
  • jobs.<job_id>.steps[*].id
  • contexts
• A workflow that demonstrates the needs: statement to serialize dependent jobs
• Dependent jobs can be stated as a string or an array of strings
• This example also illustrates marking a step with an id: attribute. These step id's can be used to reference different step contexts during execution

4. Checkout your GitHub repository

./try_workflow.sh workflows/04_checkout.yml

• Status:
• Workflow: 04_checkout.yml
• References:
  • actions/checkout
• An action that checks-out your repository into $GITHUB_WORKSPACE, so your workflow can access it
• Once of many ready-made GitHub Actions to simplify your workflow

5. Trigger filters

./try_workflow.sh workflows/05_trigger_filters.yml

• Status:
• Workflow: 05_trigger_filters.yml
• References:
  • trigger filters
• An example that shows how to filter the GHA triggers so only a subset of events will trigger the workflow
• In this case the pull requests are filtered down to subset of events that are listed in the types: array

6. Trigger workflow on-demand

./try_workflow.sh workflows/06_on_demand_trigger.yml

• Status:
• Workflow: 06_on_demand_trigger.yml
• References:
  • repository_dispatch
  • dispatch event
• An example of how to trigger a workflow on-demand using the GitHub API
• Once the workflow is in place, you can trigger it with the following POST request:

curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
<https://api.github.com/repos/OWNER/REPO/dispatches> \
-d '{"event_type":"on-demand-test","client_payload":{"unit":false,"integration":true}}'

• Note that the event_type in the POST request must match one of the types: strings set in the repository_dispatch trigger

7. Scheduled triggers

./try_workflow.sh workflows/07_scheduled_trigger.yml

• Status:
• Workflow: 07_scheduled_trigger.yml
• References:
  • scheduled triggers
• An example that shows how to trigger a workflow on a scheduled basis using cron syntax

8. Environment Variables

./try_workflow.sh workflows/08_env_vars.yml

• Status:
• Workflow: 08_env_vars.yml
• References:
  • environment variables
• An example that shows how to use environment variables in a workflow
• Environment variables can be set at the workflow level, the job level, or at the step level

9. Secrets

./try_workflow.sh workflows/09_secrets.yml

• Status:
• Workflow: 09_secrets.yml
• References:
  • secrets
• An example that shows how to load secrets configured in your repository into your workflow

10. GitHub Tokens

./try_workflow.sh workflows/10_github_tokens.yml

• Status:
• Workflow: 10_github_tokens.yml
• References:
  • Automatic token authentication
• An example of how you can use a GITHUB_TOKEN secret in your workflow when you need to authenticate in a workflow run

11. Decrypt GPG-encrypted files

./try_workflow.sh workflows/11_decrypt_gpg.yml

• Status:
• Workflow: 11_github_tokens.yml
• References:
  • GPG-encrypted files
• An example of how you can unencrypt a GPG-encrypted file in your workflow
• This is using a simple symmetric cipher to perform the encryption
• The my_secret_json.gpg file was encrypted using a passphrase to protect the secret. The following command performs the encryption:

gpg --symmetric --cipher-algo AES256 my_secret.json

• The GPG_PASSPHRASE is configured in the repository's secrets so that it may be used in the workflow to unecrypt the file

12. Contexts

./try_workflow.sh workflows/12_contexts.yml

• Status:
• Workflow: 12_contexts.yml
• References:
  • Contexts
• An example workflow showing various GHA contexts
• Contexts provide access to information about workflow runs, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects.

13. Functions

./try_workflow.sh workflows/13_functions.yml

• Status:
• Workflow: 13_functions.yml
• References:
  • Functions
• An example workflow showing some of the GHA functions available
• The number of functions is limited, so you consider other tooling if you need more functionality

14. Conditional Steps

./try_workflow.sh workflows/14_conditionals.yml

• Status:
• Workflow: 14_conditionals.yml
• References:
  • jobs.<job_id>.if
  • Status Checks
• An example workflow showing how you can use conditional steps to control whether subsequent steps execute

15. Matrix Strategy

./try_workflow.sh workflows/15_matrix_strategy.yml

• Status:
• Workflow: 15_matrix_strategy.yml
• References:
  • Matrix Strategy
• An example workflow showing how a matrix strategy can define a single job that automatically creates multiple jobs based on the matrix values
• Very useful when you need to run test code against multiple versions and/or operating systems

16. Containers

./try_workflow.sh workflows/16_containers.yml

• Status:
• Workflow: 16_containers.yml
• References:
  • jobs.<job_id>.container
  • Job in a container
• An example workflow showing how to run a GHA job inside a container
• An option to consider if you need a container environment or a specialized environment beyond the standard GHA runners available

17. Multiple Containers

./try_workflow.sh workflows/17_multi_containers.yml

• Status:
• Workflow: 17_multi_containers.yml
• References:
  • jobs.<job_id>.services
• An example workflow showing how to run a GHA job with a set of container-based services
• An option to consider when testing a job that requires a backend service (e.g. API + database)

18. Customize Containers

./try_workflow.sh workflows/18_customize_containers.yml

• Status:
• Workflow: 18_customize_containers.yml
• References:
  • jobs.<job_id>.steps[*].uses
• An example workflow showing how you can further customize a container image taken from Docker Hub and used in a GHA step

19. Override Entrypoint

./try_workflow.sh workflows/19_override_entrypoint.yml

• Status:
• Workflow: 19_override_entrypoint.yml
• References:
• jobs.<job_id>.steps[*].with.entrypoint
• An example workflow using a container image which overrides the default entrypoint with a local script

20. Message Slack

./try_workflow.sh workflows/20_message_slack.yml

• Status:
• Workflow: 20_message_slack.yml
• References:
• A container for sending Slack messages
• An example workflow using a custom container image to send Slack messages

21. Upload Artifact

./try_workflow.sh workflows/21_upload_artifact.yml

• Status:
• Workflow: 21_upload_artifact.yml
• References:
• Upload Artifact
• Download Artifact
• An example showing how you can upload artifacts from your workflow to share data between jobs and store data once a workflow is complete.
• Note that the uploaded artifact is available for 90 days and it can be found in the Actions tab, at the bottom of the workflow's summary page.

22. Auto Merge

./try_workflow.sh workflows/22_auto_merge.yml

• Status:
• Workflow: 22_auto_merge.yml
• References:
• Auto Approve
• Merge PR
• An example showing how you can auto-approve and auto-merge a PR using GHA
• Note that this will only work if the PR is opened by github.actor netserf.

Attributions

• Many of these examples are based on the lessons from Udemy's The Complete GitHub Actions & Workflows Guide authored by Ali Alaa.
  • This is an excellent course.
  • Highly recommend if you want to learn more about GitHub Actions.