Developing for emulate

Repository Layout

• action.yml
  • This file defines the GitHub Action and all of the inputs. It also serves as the starting point when a user adds "mario-campos/emulate" to a workflow and runs it. The starting point is a single Bash run step that resolves some "alias" identifiers and "spins up" the VM with Vagrant.
• BASH_ENV
  • This file is a Bash shell script that does a few things, but most importantly, it "steals" control of the bash process that is executed whenever a run step is evaluated. It's important that we "hijack" it (with the use of the BASH_ENV environment variable), because it allows us to proxy the contents of the run step to the VM, rather than run it in the runner host.
• $OS-$OS_VERSION
  • These directories contain all of the scripts/code necessary to build and run the Vagrant box. Note that these directories contains files for both creating the Vagrant box of the same name (with Packer), and also for booting a Vagrant VM for said box later (with Vagrant). Although the files share the same directory, it is only for convenience.
• $OS-$OS_VERSION/.pkr.hcl
  • This file is the Packer template file which defines the steps and commands necessary to build the Vagrant box for $OS-$OS_VERSION. Note that this file, and any other files it references, are only relevant for building the Vagrant box that will be subsequently downloaded and spun up.
• $OS-$OS_VERSION/Vagrantfile
  • This file is the Vagrantfile that controls the VM, such as VirtualBox settings, SSH settings, Box download settings, etc. Although this file is stored in the $OS-$OS_VERSION directory, along with the Packer files, it has no impact on the creation of the Box; the impacts of changing this file occurs when the Action is evaluated, after the Box has been created and uploaded.

Development Environment

Tools

• Hashicorp Packer
• Hashicorp Vagrant
• Oracle Virtualbox
• GitHub CLI

Ensure that you are fully authenticated to both GitHub and Vagrant Cloud. For Vagrant Cloud, the environment variable VAGRANT_CLOUD_TOKEN should be set. For GitHub, ensure that gh auth status is successful.

Debugging

To view the VirtualBox GUI when building with Packer, set the headless variable to false like so:

packer build -var headless=false openbsd-7.0

New Release

1. Make any changes to release files, such as to .pkr.hcl, that might impact the new Vagrant box.
2. Build the new Vagrant box and upload it to Vagrant Cloud:

packer build openbsd-7.0

3. Commit the changes to the local git repository.
4. Push the commits:

git push origin main

5. Create a git tag and release from the new commit(s):

gh release create openbsd-7.0_0.1.3 packer_default_virtualbox.box

6. Generate the SHA256 checksum of the new box.

shasum -a 256 packer_default_virtualbox.box

7. Update Vagrantfile, modifying box_download_checksum and box_url with the new SHA256 checksum and URLs, respectively.
8. Commit the changes to Vagrantfile.
9. Push the commit(s) once more:

git push origin main

10. Update the v1 git tag to make the change visible to users:

git tag -f v1
git push -f origin v1