From ba450c745ca3bf810aed7f4dff3e57bcd6ee2ff8 Mon Sep 17 00:00:00 2001 From: Ragnarok <260221049+librerob@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:16:13 +0000 Subject: [PATCH] Add dependency updates, bug forms and release integrity checks --- .github/ISSUE_TEMPLATE/bug-report.yml | 76 ++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/dependabot.yml | 13 ++ .github/workflows/release-verification.yml | 54 +++++++ CONTRIBUTING.md | 21 +++ README.md | 2 +- maintenance/README.md | 33 +++++ tests/test_release_verification.py | 117 +++++++++++++++ tools/verify_release.py | 159 +++++++++++++++++++++ 9 files changed, 479 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/release-verification.yml create mode 100644 tests/test_release_verification.py create mode 100644 tools/verify_release.py diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..eb74337 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,76 @@ +name: Report a theme or installer problem +description: Help reproduce a visual, application, icon or installation problem. +title: '[Bug]: ' +body: + - type: dropdown + id: area + attributes: + label: Which part is affected? + options: + - GTK application styling + - GNOME Shell + - Cinnamon desktop / panel / menu + - Window decorations or another desktop + - Folder icons + - Qt or application extras + - Installer / update / removal + - Other / unsure + validations: + required: true + - type: textarea + id: environment + attributes: + label: Versions and environment + description: Unknown versions are fine—include what you know. + value: | + Distribution and version: + Desktop and version: + Theme version (release or commit): + Theme accent / folder color: + Application and version (or install.sh): + X11 or Wayland, if known: + validations: + required: true + - type: dropdown + id: installation + attributes: + label: How was the theme installed? + options: + - Guided installer from a release download + - Installer with command-line options + - Installer from a Git checkout + - Manual installation + - Other / unsure + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Include the installer command/options if relevant. + placeholder: '1. Open the application…' + validations: + required: true + - type: textarea + id: expected + attributes: + label: What did you expect? + validations: + required: true + - type: textarea + id: actual + attributes: + label: What happened instead? + description: Paste the exact error if there is one. + validations: + required: true + - type: textarea + id: screenshots + attributes: + label: Screenshots + description: Drag images here for visual problems. Include the affected widget and surrounding window. + - type: textarea + id: details + attributes: + label: Relevant logs or customizations (optional) + description: Mention extensions, other GTK overrides or Flatpak packaging if relevant. Include only relevant logs; do not paste secrets or a full environment dump. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..11ffca3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Installation and application setup + url: https://github.com/librerob/adwaita-amoled/blob/main/INSTALLING.md + about: Destinations, manual alternatives, GTK4, Flatpak and application-specific instructions. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..98ad976 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,13 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: monthly + time: '09:30' + timezone: Europe/London + open-pull-requests-limit: 3 + groups: + github-actions: + patterns: + - '*' diff --git a/.github/workflows/release-verification.yml b/.github/workflows/release-verification.yml new file mode 100644 index 0000000..7c9f2e1 --- /dev/null +++ b/.github/workflows/release-verification.yml @@ -0,0 +1,54 @@ +name: Release verification + +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: 'Release tag (leave blank for the latest stable release)' + required: false + type: string + pull_request: + paths: + - '.github/workflows/release-verification.yml' + - 'tools/verify_release.py' + - 'tools/package.py' + - 'tests/test_release_verification.py' + push: + branches: [main] + paths: + - '.github/workflows/release-verification.yml' + - 'tools/verify_release.py' + - 'tools/package.py' + - 'tests/test_release_verification.py' + +permissions: + contents: read + +jobs: + verify: + if: github.event_name != 'release' || !github.event.release.prerelease + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ github.event_name == 'pull_request' && github.ref || github.event.repository.default_branch }} + fetch-depth: 0 + persist-credentials: false + - name: Test archive integrity and unsafe-input rejection + run: python3 tests/test_release_verification.py + - name: Verify published archive against its tag + env: + GH_TOKEN: ${{ github.token }} + RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }} + run: python3 tools/verify_release.py --tag "$RELEASE_TAG" --output '${{ runner.temp }}/release-verification' + - name: Save verification report + if: always() + uses: actions/upload-artifact@v7 + with: + name: release-verification-report + path: ${{ runner.temp }}/release-verification + retention-days: 90 + if-no-files-found: warn diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff18b32..3c449c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,3 +86,24 @@ The [monthly upstream watch](maintenance/README.md) reports new release tags and links to component-specific review/test guidance. It does not modify the theme or establish compatibility automatically. Update review baselines only after recording the relevant checks and limits in `COMPATIBILITY.md`. + +## Release integrity + +After publishing a stable release with its runtime archive attached, check the +[Release verification workflow](https://github.com/librerob/adwaita-amoled/actions/workflows/release-verification.yml). +Use **Run workflow** to verify an older release or an asset uploaded after +publication. Verification is read-only; it does not publish releases. + +For local development, use Python 3.11+, authenticated GitHub CLI and a checkout +with the requested release tag fetched: + +```bash +python3 tests/test_release_verification.py +git fetch origin tag v1.9.0 +python3 tools/verify_release.py --tag v1.9.0 --output /tmp/adwaita-release-report +``` + +The verifier uses this checkout's packager with tagged source as data. Preserve +compatibility with existing archives when changing the packaging format, or +extend verification deliberately. See [maintenance guidance](maintenance/README.md#other-repository-maintenance) +for report details and the other repository automation. diff --git a/README.md b/README.md index 4ba9960..434b349 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,6 @@ for tested versions and coverage limits. ## Feedback -[Report a problem or contribute](https://github.com/librerob/adwaita-amoled/issues). +[Report a problem](https://github.com/librerob/adwaita-amoled/issues/new?template=bug-report.yml) or [contribute](CONTRIBUTING.md). Include your distribution, desktop/version, application, selected accent and theme version so the problem can be reproduced. diff --git a/maintenance/README.md b/maintenance/README.md index cf9c9d8..e3621cc 100644 --- a/maintenance/README.md +++ b/maintenance/README.md @@ -86,3 +86,36 @@ GitHub can disable scheduled workflows on inactive public repositories after 60 days. If reports stop appearing, check the Actions page for a re-enable banner. The watch does not detect unreleased branch changes, distribution-only patches, arbitrary application CSS or hardware-specific rendering problems. + +## Other repository maintenance + +Dependabot checks GitHub Actions dependencies monthly and groups updates into +one pull request. Review the changes and passing checks before merging; automatic +merging is not configured. This does not update theme imports or palettes. + +The [bug-report form](https://github.com/librerob/adwaita-amoled/issues/new?template=bug-report.yml) +asks for the desktop, theme version, accent, installation method and reproduction +steps, with space for screenshots. Blank issues remain available. + +Secret scanning and push protection are managed in repository **Settings → +Advanced Security / Secret protection**. Keep both enabled. They detect supported +credential patterns; they do not establish that code or an installer is safe. + +[Release verification](https://github.com/librerob/adwaita-amoled/actions/workflows/release-verification.yml) +runs when a stable release is published, and when its verification code changes. +To check an existing release, choose **Run workflow**, select `main` and enter +its tag, or leave the tag blank for the latest stable release. + +The verifier downloads the uploaded `Adwaita-AMOLED-vX.Y.Z.tar.gz`, rebuilds the +runtime archive from that tag's data using the current trusted packager, and +requires a byte-for-byte match. It also checks the archive's file checksums and +the included accent/icon checksum manifests. It never runs build scripts or the +installer from the release tag. A packaging-format change may require updating +the verifier to retain compatibility with older archives. + +Open the run's **Summary** for the result, commit, tree and archive SHA-256. +The **release-verification-report** artifact retains Markdown and JSON reports +for 90 days. Missing, corrupted or mismatched assets fail verification. This +checks release integrity, not application rendering or desktop compatibility. +It does not publish, repair or modify a release. If assets are uploaded after +publication or replaced later, run verification again manually. diff --git a/tests/test_release_verification.py b/tests/test_release_verification.py new file mode 100644 index 0000000..34fc542 --- /dev/null +++ b/tests/test_release_verification.py @@ -0,0 +1,117 @@ +"""Published archives must match tag data; no tagged build code may execute.""" +import contextlib +import io +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import tarfile +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools')) +import package as packaging +import verify_release as verifier + + +def git(root, *args): + return subprocess.check_output(['git', '-c', 'user.name=Release verifier test', + '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', + '-c', 'core.hooksPath=/dev/null', *args], cwd=root, stderr=subprocess.DEVNULL) + + +def build(root, target): + before_root, before_argv = packaging.ROOT, sys.argv + try: + packaging.ROOT = root;sys.argv = ['package.py', str(target)] + with contextlib.redirect_stdout(io.StringIO()):packaging.main() + finally: + packaging.ROOT, sys.argv = before_root, before_argv + + +class ReleaseVerificationTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.temporary = tempfile.TemporaryDirectory(prefix='amoled-verifier-tests-') + cls.base = Path(cls.temporary.name);cls.source = cls.base / 'original';cls.source.mkdir() + for name in packaging.runtime_paths(ROOT) + packaging.accent_paths(ROOT): + target = cls.source / name;target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(ROOT / name, target) + # A tagged script is deliberately hostile. The verifier must only use + # the current trusted packager, treating the tag's files as inert data. + (cls.source / 'tools').mkdir() + (cls.source / 'tools/package.py').write_text('raise RuntimeError("TAG CODE EXECUTED")\n') + git(cls.source, 'init', '-q');git(cls.source, 'add', '.') + git(cls.source, 'commit', '-qm', 'fixture') + git(cls.source, 'tag', 'v99.0.0') + git(cls.source, 'tag', '-a', 'v99.0.1', '-m', 'Annotated fixture') + cls.archive = cls.base / 'original.tar.gz';build(cls.source, cls.archive) + + @classmethod + def tearDownClass(cls):cls.temporary.cleanup() + + def setUp(self): + self.work = Path(tempfile.mkdtemp(dir=self.base)) + self.addCleanup(shutil.rmtree, self.work) + + def clone(self): + root = self.work / 'repository' + git(self.base, 'clone', '-q', '--local', str(self.source), str(root)) + return root + + def verify(self, root, tag='v99.0.0', archive=None): + with contextlib.redirect_stdout(io.StringIO()): + return verifier.verify_archive(root, tag, archive or self.archive) + + def test_exact_archive_and_lightweight_or_annotated_tag_pass_without_tag_code(self): + for tag in ('v99.0.0', 'v99.0.1'): + report = self.verify(self.source, tag) + self.assertEqual(report['source_match'], 'byte-for-byte') + self.assertFalse(report['tag_code_executed']) + self.assertGreater(report['checksum_entries'], report['files']) + self.assertEqual(report['commit'], git(self.source, 'rev-parse', 'HEAD').decode().strip()) + + def test_corrupt_or_missing_archive_fails(self): + damaged = self.work / 'bad.tar.gz';data = bytearray(self.archive.read_bytes());data[-1] ^= 1 + damaged.write_bytes(data) + with self.assertRaisesRegex(ValueError, 'differs from tagged source'): + self.verify(self.source, archive=damaged) + with self.assertRaises(FileNotFoundError):self.verify(self.source, archive=self.work / 'absent.tar.gz') + + def test_archive_from_different_source_commit_fails(self): + root = self.clone();(root / 'README.md').write_text('Different release source\n') + git(root, 'add', 'README.md');git(root, 'commit', '-qm', 'change') + git(root, 'tag', 'v99.0.2') + with self.assertRaisesRegex(ValueError, 'differs from tagged source'): + self.verify(root, 'v99.0.2') + + def test_unknown_or_unsafe_tags_fail(self): + for name in ('main', '../../elsewhere', '--help', 'v99.0.0;echo nope'): + with self.assertRaisesRegex(ValueError, 'stable tag'):self.verify(self.source, name) + with self.assertRaisesRegex(ValueError, 'Command failed'):self.verify(self.source, 'v99.9.9') + + def test_self_consistent_package_with_bad_internal_icon_manifest_fails(self): + root = self.clone();manifest = root / 'extra/icons/Adwaita-AMOLED/SHA256SUMS' + text = manifest.read_text();manifest.write_text('0' * 64 + text[64:]) + git(root, 'add', '.');git(root, 'commit', '-qm', 'bad internal checksum');git(root, 'tag', 'v99.0.2') + archive = self.work / 'bad-manifest.tar.gz';build(root, archive) + with self.assertRaisesRegex(ValueError, 'Checksum mismatch'):self.verify(root, 'v99.0.2', archive) + + def test_invalid_checksum_paths_and_duplicate_entries_are_rejected(self): + digest = '0' * 64 + for text in (digest + ' ../escape\n', digest + ' /absolute\n', + digest + ' ok\n' + digest + ' ok\n', ''): + with self.assertRaises(ValueError):verifier.verify_manifest(text.encode(), lambda _: b'content') + + def test_runtime_symlink_is_rejected_without_reading_its_target(self): + root = self.clone();readme = root / 'README.md';readme.unlink() + target = self.work / 'private.txt';target.write_text('untouched') + readme.symlink_to(target) + git(root, 'add', '.');git(root, 'commit', '-qm', 'linked payload');git(root, 'tag', 'v99.0.2') + with self.assertRaises((ValueError, SystemExit, tarfile.FilterError)): + self.verify(root, 'v99.0.2') + self.assertEqual(target.read_text(), 'untouched') + + +if __name__ == '__main__':unittest.main(verbosity=2) diff --git a/tools/verify_release.py b/tools/verify_release.py new file mode 100644 index 0000000..52a871e --- /dev/null +++ b/tools/verify_release.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +"""Verify an uploaded runtime archive using tagged source as data, never code.""" +import argparse +import hashlib +import io +import json +import os +from pathlib import Path +import re +import subprocess +import sys +import tarfile +import tempfile + +import package as packaging + +ROOT = Path(__file__).resolve().parents[1] +REPOSITORY = 'librerob/adwaita-amoled' +TAG = re.compile(r'v\d+\.\d+\.\d+') +RELATIVE = re.compile(r'[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*') + + +def command(args, cwd=None): + result = subprocess.run(args, cwd=cwd, capture_output=True, timeout=120) + if result.returncode: + raise ValueError('Command failed: ' + ' '.join(str(a) for a in args[:4])) + return result.stdout + + +def valid_path(name): + return bool(RELATIVE.fullmatch(name)) and all(p not in ('.', '..') for p in name.split('/')) + + +def verify_manifest(data, resolve): + seen = set() + for line in data.decode('utf-8').splitlines(): + digest, separator, name = line.partition(' ') + if not separator or not re.fullmatch('[0-9a-f]{64}', digest) or not valid_path(name) or name in seen: + raise ValueError('Invalid checksum manifest entry') + seen.add(name) + if hashlib.sha256(resolve(name)).hexdigest() != digest: + raise ValueError('Checksum mismatch: ' + name) + if not seen: + raise ValueError('Empty checksum manifest') + return len(seen) + + +def source_file(root, name): + if not valid_path(name):raise ValueError('Invalid manifest path') + path = root / name + if any(p.is_symlink() for p in (path, *path.parents) if p != root) or not path.is_file(): + raise ValueError('Missing or linked payload file: ' + name) + return path.read_bytes() + + +def verify_archive(repository, tag, archive): + if not TAG.fullmatch(tag):raise ValueError('Expected a stable tag such as v1.9.0') + commit = command(['git', 'rev-parse', '--verify', f'refs/tags/{tag}^{{commit}}'], repository).decode().strip() + tree = command(['git', 'rev-parse', f'{commit}^{{tree}}'], repository).decode().strip() + with tempfile.TemporaryDirectory(prefix='amoled-release-verify-') as temporary: + work = Path(temporary);source = work / 'source';source.mkdir() + # No checkout hooks, build scripts, installers or Python from the tag run. + exported = command(['git', 'archive', '--format=tar', commit], repository) + with tarfile.open(fileobj=io.BytesIO(exported)) as bundle: + bundle.extractall(source, filter='data') + old_root, old_argv = packaging.ROOT, sys.argv + rebuilt = work / 'rebuilt.tar.gz' + try: + packaging.ROOT = source + sys.argv = ['package.py', str(rebuilt)] + packaging.main() # Trusted verifier checkout's packager, not tag code. + finally: + packaging.ROOT, sys.argv = old_root, old_argv + expected = hashlib.sha256(rebuilt.read_bytes()).hexdigest() + actual = hashlib.sha256(archive.read_bytes()).hexdigest() + if actual != expected: + raise ValueError(f'Uploaded archive differs from tagged source: expected SHA-256 {expected}; got {actual}') + checks = 0 + # Validate every included source SHA256SUMS, including sparse overlays. + for manifest in source.rglob('SHA256SUMS'): + relative = manifest.relative_to(source) + if not (str(relative).startswith('accents/') or str(relative).startswith('extra/icons/')): + continue + def resolve(name, directory=manifest.parent): + path = directory / name + if path.is_file():return source_file(source, str(path.relative_to(source))) + # An accent icon manifest includes shared base files as well as + # changed overlay files; check the merged installed view. + parts = path.relative_to(source).parts + if len(parts) > 2 and parts[0] == 'accents': + return source_file(source, '/'.join(parts[2:])) + raise ValueError('Missing manifest file: ' + name) + checks += verify_manifest(source_file(source, str(relative)), resolve) + with tarfile.open(rebuilt, 'r:gz') as bundle: + members = bundle.getmembers() + names = [m.name for m in members] + if len(names) != len(set(names)) or any(not m.isfile() or not m.name.startswith('Adwaita-AMOLED/') for m in members): + raise ValueError('Invalid archive member layout') + def payload(name): + member = bundle.getmember('Adwaita-AMOLED/' + name) + return bundle.extractfile(member).read() + checks += verify_manifest(payload('ARCHIVE_CONTENTS.sha256'), payload) + return {'tag': tag, 'commit': commit, 'tree': tree, 'sha256': actual, + 'bytes': archive.stat().st_size, 'files': len(members), 'checksum_entries': checks, + 'source_match': 'byte-for-byte', 'tag_code_executed': False} + + +def verify_published(repository, tag): + route = f'repos/{REPOSITORY}/releases/tags/{tag}' if tag else f'repos/{REPOSITORY}/releases/latest' + release = json.loads(command(['gh', 'api', route])) + tag = release['tag_name'] + if release['draft'] or release['prerelease'] or not TAG.fullmatch(tag): + raise ValueError('Expected a published stable release') + expected_name = f'Adwaita-AMOLED-{tag}.tar.gz' + assets = [a for a in release['assets'] if a['name'] == expected_name] + if len(assets) != 1:raise ValueError('Expected exactly one uploaded asset: ' + expected_name) + asset = assets[0] + if asset['state'] != 'uploaded' or not 0 < asset['size'] <= 64 * 1024 * 1024: + raise ValueError('Release asset is incomplete or exceeds the verifier size limit') + with tempfile.TemporaryDirectory(prefix='amoled-release-download-') as temporary: + command(['gh', 'release', 'download', tag, '--repo', REPOSITORY, + '--pattern', expected_name, '--dir', temporary]) + archive = Path(temporary) / expected_name + if archive.stat().st_size != asset['size']:raise ValueError('Downloaded asset size mismatch') + digest = 'sha256:' + hashlib.sha256(archive.read_bytes()).hexdigest() + if asset.get('digest') and asset['digest'] != digest:raise ValueError('GitHub asset digest mismatch') + report = verify_archive(repository, tag, archive) + report.update(release_url=release['html_url'], asset=expected_name, github_digest=asset.get('digest')) + return report + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--tag', default='') + parser.add_argument('--output', type=Path, required=True) + args = parser.parse_args() + args.output.mkdir(parents=True, exist_ok=True) + try: + if args.tag and not TAG.fullmatch(args.tag):raise ValueError('Expected a stable tag such as v1.9.0') + report = verify_published(ROOT, args.tag) + report['result'] = 'PASS' + summary = (f"# Release verification: PASS\n\n[{report['tag']}]({report['release_url']})\n\n" + f"- Uploaded archive matches tagged source byte-for-byte.\n- All included checksum manifests passed.\n" + f"- Commit: `{report['commit']}`\n- Tree: `{report['tree']}`\n- SHA-256: `{report['sha256']}`\n" + f"- Files: {report['files']}; checksum entries: {report['checksum_entries']}.\n\n" + 'No release or repository files were changed. This is an integrity check, not a new rendering test.\n') + except (OSError, ValueError, KeyError, tarfile.TarError, subprocess.TimeoutExpired, SystemExit) as error: + report = {'result': 'FAIL', 'error': str(error)} + summary = '# Release verification: FAIL\n\n' + str(error) + '\n' + (args.output / 'verification.json').write_text(json.dumps(report, indent=2) + '\n') + (args.output / 'verification.md').write_text(summary) + if os.environ.get('GITHUB_STEP_SUMMARY'): + with open(os.environ['GITHUB_STEP_SUMMARY'], 'a') as stream:stream.write(summary) + print(summary) + return 0 if report['result'] == 'PASS' else 1 + + +if __name__ == '__main__': + raise SystemExit(main())