Skip to content

Setting up Github Actions

Jump to bottom
Dan Walkes edited this page Oct 23, 2024 · 33 revisions

Overview

This page details the requirements for setting up your build host to run Github Actions. Github Actions may be run on your Development Host or another host setup as shown below.

For Development Host requirements, see this page.

Initial setup

Setup automated testing for your assignment repository following the instructions at https://docs.github.com/en/actions/hosting-your-own-runners/adding-self-hosted-runners.

  1. You must use a Linux (x86_64) based runner for the assignments.
  2. You must also ensure your runner machine has docker engine installed. See install instructions here for Ubuntu. Make sure you install docker engine from the link above and not docker desktop as distributed by your Linux distribution.
    • You must also configure Docker to run as a non-root user on your machine. See the Post install steps for Linux for instructions. Either reboot your machine, restart the command prompt associated with your runner, or run the newgrp command referenced in the instructions to apply group permissions.
    • Alternatively you can run this script to perform the above step docker_install.sh
  3. See instructions in the Setting up your host section of the assignment autotest repository to setup your host to run your tests outside self hosted runners.
    • Your runner should installed to a directory outside your repository, and you should not add any files associated with your self hosted runner setup to your assignment git repository.

Re-using a previously configured runner

To re-use a previously configured runner from a previous assignment you can remove it first from your previously completed assignment repository using https://docs.github.com/en/actions/hosting-your-own-runners/removing-self-hosted-runners.

Then re-follow the instructions at https://docs.github.com/en/actions/hosting-your-own-runners/adding-self-hosted-runners to add to your next assignment repository. You only need to perform the step which associates the runner with your new repository since you've already downloaded and extracted the runner itself.

Please note that buildroot actions runners do not perform clean builds. Therefore, if you reuse an actions runner buildroot directory but change configuration to add packages, you'll need to manually clean, install config changes, or just restart with an empty actions runner directory to pick up the changes.

Using an SSH key with your runner

Assignments which use buildroot or yocto (assignments 4 and later) require a github secret to access your assignment 3 and earlier repository. This configuration must be set on each repository containing buildroot or yocto source. In other words, you must set this secret in the repository you use with buildroot or yocto build scripts.

  1. Generate an SSH key with with empty passphrase using these instructions. Tip: use a name like “aeld_id_rsa_nopassphrase” when creating.
  2. Add to your account using instructions here
  3. Copy the entire content of the private key file (including any headers/footers like -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----) [and make sure you don't copy any white spaces] into a secret named SSH_PRIVATE_KEY using the instructions in this link
image

Github Runner Validation

When successfully configured, you should see a green checkbox indicating a successful check for the assignment automated tests. image

Browsing the "Actions" tab should show a successful result for the most recent commit image

Clicking on the most recent action and viewing the job logs for unit-test and/or full-test scripts should show the same result you see when running these scripts from your host build system, with all tests passing. image

Troubleshooting

SSH Access Issues

To verify your private key works with your repository clone: First use

ssh-agent

to start the SSH agent in your terminal window.

  • Then use ssh-add <path to keyfile> to add the same key you added to your github secret.
  • Finally, attempt to clone your repository using the SSH URL found in your target github repository.
  • If this works, your key should also work with github actions, provided you have included the full content of your private key file in the definition of the SSH_PRIVATE_KEY variable.

Docker run issues

If you see an issue which looks like this:

The uid:gid for "your-path-here" is "0:0". The uid and gid must be non-zero. Please check to make sure the "volume" or "bind" specified using either "-v" or "--mount" to docker, exists and has a non-zero uid:gid.

It's likely because you have docker desktop installed instead of the docker engine. Refer to the instructions linked above to uninstall docker desktop and install docker engine. See related discussion at https://github.com/cu-ecen-aeld/assignment-autotest/issues/34

Failures only on actions runner

If you are able to run local tests successfully but see failures when running with the autotest runner it's possible you have corrupted state on your actions runner. This is especially true for assignments 3 and later.

To ensure actions runner state is not the issue, you should deregister your actions runner, completely delete your actions runner directory, then re-register your actions runner.

Alternatively, you may delete your _work directory under your actions runner to ensure it starts with an empty state for the next run.

Clone this wiki locally