GitHub supports workflow automation in the cloud through Github Actions. This feature is very useful for automating builds, deployment and other aspects of continuous integration.
Services
SciJava projects use Github Actions in a variety of ways:
- Perform builds of SciJava projects. Github Actions deploy
SNAPSHOTbuilds to the SciJava Maven repository in response to pushes to each code repository’smasterbranch. So any downstream projects depending on a version ofLATESTfor a given component will match the last successful Github build—i.e., the latest code onmaster. - Run each project’s associated unit tests. Github Actions is instrumental in early detection of new bugs introduced to the codebase.
- Perform releases of SciJava projects. Github Actions deploys release builds to the appropriate Maven repository—typically either the SciJava Maven repository or OSS Sonatype.
- Keep the javadoc site updated.
- Keep other web resources updated.
Automatic Deployment of Maven Artifacts
Deploying your library to a Maven repository makes it available for other developers. It is also a contribution requirement for the Fiji project.
Requirements
- Host your open-source project on GitHub.
- Contact an ImageJ admin on the Image.sc Zulip or the Image.sc Forum and request that they add the authentication secrets for deployment to your organization.
Instructions
- In order to add Github CI support to a repository, the secrets are needed: A) for deploying to Maven repositories; and B) in the case of deploying to OSS Sonatype, for GPG signing of artifacts.
- If the secrets have been added to your organization, and you have push access to the relevant repository on GitHub, you can use the github-actionify.sh script with the
-fflag to perform the needed operations. - The github-actionify script will return ‘[ERROR] Dirty working copy’ if you have uncommited changes. If you get this error, check the status of the repository with
git statusand then rungithub-actionify -fagain. - If you need help, please ask on the Image.sc Forum in the Development category, or in the SciJava stream on the Image.sc Zulip.
Configuration of JavaFX builds
- The workflows configured by the github-actionify.sh script do not include JavaFX.
- To add support for JavaFX, edit the files contained in the folder
.github/workflows/to match those found in other SciJava projects that depend on JavaFX, e.g. FilamentDetector.
Testing things which cannot run headless
If your tests require a display (i.e.: they do not pass when run headless), you will get errors during the build process such as:
No X11 DISPLAY variable was set, but this program performed an operation which requires it.
Error: myTest Time elapsed: 0.097 s <<< ERROR!
You can fix this using Xvfb as follows.
In your repository there is a file .github/workflows/build-main.yml.
In this file there should be some lines that read:
- name: Set up CI environment
run: .github/setup.sh
- name: Execute the build
run: .github/build.sh
If you amend and change those lines as shown below, also tests that require a display should work.
- name: Set up CI environment
run: .github/setup.sh
- name: Install xvfb
run: sudo apt-get install xvfb
- name: Execute the build using xfvb
run: xvfb-run --auto-servernum .github/build.sh
Of course, you should do this only as a last resort, since the best unit tests should not require a display in the first place.
