Skip to content
FlickOS

CI and releases

Where things are published

Section titled “Where things are published”
What Where
ISO downloads SourceForge Files: https://sourceforge.net/projects/flickos/files/ (one folder per release, e.g. v2.0/)
Apt repository GitHub Pages (dvbondoy/flickos-apt): https://dvbondoy.github.io/flickos-apt/ (05)
Source code, CI, issues GitHub: https://github.com/dvbondoy/FlickOS
Website https://flickos.net (planned)

Release history: FlickOS 1.0 and 1.1 (FlickOS-64bit-v1.1.iso, May 2023) were based on Ubuntu 20.04 and LXLE. FlickOS 2.0 is a rebuild on Debian 13. There is no in-place upgrade from 1.x to 2.0. Release notes must tell 1.x users to back up their files and reinstall.

The version number

Section titled “The version number”

FLICKOS_VERSION in packages/flickos-branding/usr/lib/flickos-release is the single source of the FlickOS version:

Uses it How
ISO file name tools/build-iso.sh names the ISO FlickOS-64bit-v2.0.iso
ISO volume label auto/config reads it for --iso-volume "FlickOS 2.0 amd64"
/etc/os-release, /etc/issue Generated by flickos-branding (09)
SourceForge folder tools/upload-release.sh uploads to files/v2.0/
Git tag CI refuses a tag that isn’t v + FLICKOS_VERSION
Boot test Check FlickOS version matches build

One copy can’t read that file: the installer’s packages/flickos-installer/etc/calamares/branding/flickos/branding.desc (version, shortVersion, versionedName, shortVersionedName). tools/build-iso.sh stops with Version mismatch if you forget to update it.

The workflow: .github/workflows/iso.yml

Section titled “The workflow: .github/workflows/iso.yml”

GitHub Actions builds the ISO on a clean machine so builds don’t depend on your laptop.

When it runs

Section titled “When it runs”
Trigger Result
Push to main ISO built and boot-tested, uploaded as a workflow artifact (kept 7 days)
Pull request Same. Checks the change doesn’t break the build or the boot
Manual (Actions tab → Build ISO → Run workflow) Same
Push a tag vX.Y (e.g. v2.0) Same, plus upload of the ISO and SHA256SUMS to SourceForge, and a GitHub Release with SHA256SUMS and a download link

What it does

Section titled “What it does”
  1. Starts a privileged debian:trixie container. live-build needs root, mount and chroot, and must match the target release.
  2. Installs the build tools (live-build, debhelper, …, and sfwbar’s Build-Depends), the test tools (qemu-system-x86, xorriso, python3) and the upload tools (rsync, openssh-client). wget is listed explicitly because live-build’s firmware step needs it and --no-install-recommends would skip it.
  3. Checks out the repo.
  4. On tags only: checks the tag equals v + FLICKOS_VERSION.
  5. tools/build-iso.sh --purge: builds the FlickOS packages from the commit being tested, then FlickOS-64bit-vX.Y.iso and SHA256SUMS. It’s the same script you run locally.
  6. tools/boot-test.py: boots the ISO headless and runs the checks. See 02. A failed check fails the workflow and shows as an error annotation on the run.
  7. Uploads the boot-test artifact (serial.log, screen.png, build.log), even when an earlier step failed, so you can see why.
  8. Uploads the flickos-iso artifact (ISO + SHA256SUMS).
  9. On tags only, if the SourceForge secrets are set: tools/upload-release.sh uploads the ISO and SHA256SUMS to sourceforge.net/projects/flickos/files/vX.Y/.
  10. On tags only: creates a GitHub Release with SHA256SUMS and a link to the SourceForge folder. The ISO itself isn’t attached, because GitHub release files are limited to 2 GB and FlickOS with LibreOffice can exceed that.

A tag is only uploaded and released if the build and boot test passed, because later steps don’t run after a failure. permissions: contents: write at the top allows step 10.

KVM in CI: the privileged container can use the runner’s /dev/kvm, so the boot test normally runs accelerated. If KVM isn’t available, the test prints a warning annotation and runs much slower, with longer timeouts.

One-time setup: SourceForge upload secrets

Section titled “One-time setup: SourceForge upload secrets”
  1. Create an SSH key only for CI (no passphrase): ssh-keygen -t ed25519 -N '' -C flickos-ci -f flickos-ci
  2. Add flickos-ci.pub to the SourceForge account that uploads, at https://sourceforge.net/auth/shell_services. That account must be allowed to release files in the flickos project.
  3. In GitHub → repo Settings → Secrets and variables → Actions → New repository secret:
    • SF_USER: the SourceForge username, e.g. dvbondoy
    • SF_SSH_PRIVATE_KEY: the full content of the flickos-ci file
  4. Delete the local flickos-ci private key file. If it leaks, remove the public key on SourceForge and repeat.

Without these secrets, tagged builds still work but skip the SourceForge upload. Upload by hand with tools/upload-release.sh instead.

Requirements for CI to pass

Section titled “Requirements for CI to pass”
  • The public key packages/flickos-archive-keyring/keyrings/flickos-archive-keyring.asc is committed.
  • The apt repository is published at the address in packages/flickos-archive-keyring/etc/apt/sources.list.d/flickos.sources (https://dvbondoy.github.io/flickos-apt). The build’s final apt update needs it (05).
  • The version in branding.desc matches flickos-release.
  • All scripts and hooks are committed with the executable bit. Check with git ls-files -s packages/*/debian/rules packages/*/debian/*.post* config/hooks auto repo/*.sh tools. Mode 100755 = executable, 100644 = not. Fix with git update-index --chmod=+x FILE.

The secret signing key is not needed in CI. CI only builds and uploads the ISO, it doesn’t publish the apt repository.

Getting the ISO and test results from a run

Section titled “Getting the ISO and test results from a run”

GitHub → your repo → Actions → click the run → Artifacts:

  • flickos-iso: zip containing the ISO and SHA256SUMS
  • boot-test: boot-test/serial.log, boot-test/screen.png and build.log

When the boot test fails, open serial.log first. It shows how far the boot got and the output of the failing check.

Limits

Section titled “Limits”
  • Build time is roughly 30–50 minutes, plus a few minutes for the boot test. Jobs time out after 6 hours.
  • Artifact storage counts against your GitHub quota. That’s why retention is 7 days.
  • Runner disk space is about 14 GB free. If builds fail with No space left on device, remove preinstalled tools in an extra first step, or build locally.

Release checklist

Section titled “Release checklist”

Use this for every FlickOS release. The examples use 2.0.

Prepare

  • All package changes have bumped versions (dch -i -D trixie) and are committed.
  • Shortcut for the next three items: tools/release.sh 2.0 does the version bump and the repo publish below, then waits for the new InRelease to be online (--no-publish stops after the bump). It commits nothing; run it again with the same version to resume after a failed publish. By hand:
  • Set the FlickOS version and commit:
    • FLICKOS_VERSION="2.0" in packages/flickos-branding/usr/lib/flickos-release, then bump that package (dch -i -D trixie "FlickOS 2.0.").
    • The four version strings in packages/flickos-installer/etc/calamares/branding/flickos/branding.desc, then bump that package.
  • repo/publish.sh && repo/upload.sh, then check with curl -fsSI https://dvbondoy.github.io/flickos-apt/dists/trixie/InRelease.
  • Write release notes (what’s new, known issues, and for 2.0: reinstall required when coming from 1.x).

Build and test locally (see 02)

  • tools/build-iso.sh --purge → FlickOS-64bit-v2.0.iso
  • tools/boot-test.py --strict passes.
  • tools/test-iso.sh --bios and tools/test-iso.sh --uefi: boot menu works, desktop works.
  • tools/test-iso.sh --reset --install: install with Calamares, reboot, log in, labwc starts.
  • tools/test-iso.sh --disk: sudo apt update && sudo apt upgrade works with no errors.

Publish

  • git push, and wait for CI on main to pass.
  • Tag and push:
    Terminal window
    git tag -a v2.0 -m "FlickOS 2.0"
    git push origin v2.0
  • Wait for the workflow. Without CI secrets, upload by hand: tools/upload-release.sh.
  • On SourceForge → Files → v2.0:
    • upload the release notes as README.md in that folder (SourceForge shows it below the file list),
    • click ⓘ next to FlickOS-64bit-v2.0.iso → Default Download For: select all → Save, so the big green Download button offers the new release.
  • Update the project summary/description on SourceForge if the base or features changed (for 2.0: Debian 13, labwc).
  • On GitHub → Releases → v2.0: paste the release notes.
  • Download the ISO from SourceForge and verify it: sha256sum -c SHA256SUMS.
  • Announce on r/flickos.

If a release is broken: delete the GitHub Release and the tag (git push --delete origin v2.0, git tag -d v2.0). On SourceForge, hide or delete the files in v2.0/ and restore the previous default download. Fix, set FLICKOS_VERSION="2.0.1" and release v2.0.1. Don’t reuse a version people may already have downloaded.

Version numbers: FlickOS vs packages

Section titled “Version numbers: FlickOS vs packages”

They’re independent:

  • FlickOS release (FLICKOS_VERSION, tag v2.0, ISO name): the ISO snapshot as a whole.
  • Package versions (flickos-settings 1.3): bumped whenever that package changes. Many package updates can ship between two ISO releases, through the apt repo.

Ideas for later

Section titled “Ideas for later”
  • A second workflow that publishes the apt repository when files in packages/ change. It needs the secret signing key as an encrypted GitHub secret.
  • Cache cache/ between CI runs with actions/cache to speed up builds.