flatpak-screenshots

name	flatpak-screenshots
version	1.0
last_updated	2026-07-20
id	flatpak-screenshots
one_line_purpose	Request and retrieve Flatpak app screenshots from the e2e workflow.
entry_point	docs/skills/flatpak-screenshots/SKILL.md
category	test-authoring
mcp_compliance_level	partial
status	active
dependencies	[]
tags	["flatpak","screenshots","oras"]
description	How to request and retrieve Flatpak app screenshots from the e2e workflow. Load when configuring screenshot_flatpaks or writing release workflows that consume screenshots.
metadata	{"type":"pattern","audience":"agents","maturity":"stable"}

Flatpak Screenshot Gallery

The e2e.yml reusable workflow can launch-and-screenshot any Flatpak app that is installed in the test image. This is useful for application authors who want visual evidence of their app running correctly on Bluefin, or who want a ready-made desktop screenshot for release notes or changelogs.

How it works

1. After the behave test suite completes, the workflow SSHes back into the VM.
2. For each requested app, it calls screenshot_cli.py inside the runner container (same GNOME session, same D-Bus access as the tests).
3. Each app is launched via flatpak run <app-id> (or gtk-launch for desktop apps), held open for a few seconds, then screenshotted via GNOME Shell.Eval.
4. PNGs land in the results artifact alongside test screenshots.
5. Each PNG is also pushed to GHCR as an OCI artifact with a stable per-app tag.

Workflow input

uses: projectbluefin/testsuite/.github/workflows/e2e.yml@main
with:
  image: ghcr.io/ublue-os/bluefin:latest
  suites: smoke
  screenshot_flatpaks: "org.gnome.Calculator,io.github.kolunmi.Bazaar,org.mozilla.firefox"

screenshot_flatpaks is a comma-separated list of Flatpak app IDs. Apps that are not installed in the image are skipped (the step continues with the next app).

Pulling a screenshot

After a successful run, pull any app's screenshot with oras:

# Stable tag — updated on every passing run for this image
oras pull ghcr.io/projectbluefin/testsuite/desktop-screenshot:flatpak-org-gnome-calculator-latest

# Or check the job summary for the immutable per-run ref

Tag format: flatpak-<app-id-slug>-latest where <app-id-slug> is the app ID lowercased with dots/underscores replaced by dashes.

App ID	Tag
org.gnome.Calculator	flatpak-org-gnome-calculator-latest