{"id":13752748,"url":"https://github.com/andyholmes/flatter","last_synced_at":"2025-10-28T13:09:28.074Z","repository":{"id":61717363,"uuid":"553221880","full_name":"andyholmes/flatter","owner":"andyholmes","description":"Build and host a Flatpak repository","archived":false,"fork":false,"pushed_at":"2024-10-24T06:47:16.000Z","size":3811,"stargazers_count":31,"open_issues_count":4,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-24T13:24:58.790Z","etag":null,"topics":["flatpak","github-actions","github-pages"],"latest_commit_sha":null,"homepage":"https://flatter.andyholmes.ca","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyholmes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-17T22:52:53.000Z","updated_at":"2024-10-24T06:47:20.000Z","dependencies_parsed_at":"2023-12-16T20:22:53.470Z","dependency_job_id":"a05752a3-f5ce-4abc-b495-c59c79cf88fb","html_url":"https://github.com/andyholmes/flatter","commit_stats":{"total_commits":134,"total_committers":6,"mean_commits":"22.333333333333332","dds":"0.23880597014925375","last_synced_commit":"440df4ad92bafd715444a3b59c6c81053dc57aa9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyholmes%2Fflatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyholmes%2Fflatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyholmes%2Fflatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyholmes%2Fflatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyholmes","download_url":"https://codeload.github.com/andyholmes/flatter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230061332,"owners_count":18166703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flatpak","github-actions","github-pages"],"created_at":"2024-08-03T09:01:10.447Z","updated_at":"2025-10-13T04:13:11.941Z","avatar_url":"https://github.com/andyholmes.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Flatter\n\n\u003e [!TIP]\n\u003e This action is intended for nightly or development builds for a small project.\n\u003e For more general CI tools and high-traffic use cases, see the official\n\u003e [flatpak-github-actions] and [Flathub] which has a beta channel.\n\nFlatter is a GitHub Action for building and hosting a Flatpak repository in a\nstatic hosting environment, such as GitHub Pages.\n\nThe action uses `flatpak` and `flatpak-builder` to build, sign and export\nFlatpak applications as a repository and bundles. It includes built-in caching\nto speed up builds and support an incrementally updated repository.\n\n[flatpak-github-actions]: https://github.com/flatpak/flatpak-github-actions\n[Flathub]: https://docs.flathub.org/docs/for-app-authors/submission\n\n## Table of Contents\n\n* [Complete Example](#complete-example)\n* [Inputs](#inputs)\n  * [Deployment Options](#deployment-options)\n  * [Advanced Options](#advanced-options)\n* [Outputs](#outputs)\n* [Containers](#containers)\n* [GPG Signing](#gpg-signing)\n* [Deployment](#deployment)\n  * [Flatpak Bundles](#flatpak-bundles)\n  * [GitHub Pages](#github-pages)\n  * [Custom Deploy](#custom-deploy)\n* [Multiple Architectures](#multiple-architectures)\n\n## Complete Example\n\n```yml\nname: Flatter\n\non:\n  # Rebuild once a day\n  schedule:\n    - cron: \"0 0 * * *\"\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n\n    # See \"Multiple Architectures\" below\n    strategy:\n      matrix:\n        arch: [x86_64, aarch64]\n      fail-fast: false\n      # Only one job at a time can use the shared repository cache\n      max-parallel: 1\n\n    steps:\n      # Checkout a repository with Flatpak manifests\n      - name: Checkout\n        uses: actions/checkout@v3\n\n      # See \"GPG Signing\" below\n      - name: Setup GPG\n        if: ${{ github.event_name != 'pull_request' }}\n        id: gpg\n        uses: crazy-max/ghaction-import-gpg@v5\n        with:\n          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}\n          passphrase: ${{ secrets.GPG_PASSPHRASE }}\n\n      # Generate a CNAME file on-the-fly for a configured host\n      - name: Generate CNAME\n        run: |\n          echo \"flatter.andyholmes.ca\" \u003e CNAME\n\n      - name: Build\n        uses: andyholmes/flatter@main\n        with:\n          files: |\n            build-aux/flatpak/com.example.App.json\n          arch: ${{ matrix.arch }}\n          gpg-sign: ${{ steps.gpg.outputs.fingerprint }}\n          upload-bundles: true\n          upload-pages-artifact: ${{ matrix.arch == 'aarch64' }}\n          upload-pages-includes: |\n            CNAME\n            default.css\n            index.html\n\n  # See \"Github Pages\" below\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    needs: flatter\n    permissions:\n      pages: write\n      id-token: write\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n\n    steps:\n      - name: GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n```\n\n## Inputs\n\nThe only required input is `files`, which should be a list of paths to Flatpak\nmanifests (JSON or YAML) to build.\n\n| Name                    | Default   | Description                            |\n|-------------------------|-----------|----------------------------------------|\n| `files`                 | None      | A list of paths to Flatpak manifests   |\n| `arch`                  | `x86_64`  | The architecture to build for          |\n| `gpg-sign`              | None      | A GPG Key fingerprint                  |\n| `cache-key`             | `flatter` | A cache key, or `''` to disable        |\n\nThe `files` input may be either a single-line or multi-line string value:\n\n```yml\n# One manifest\nfiles: one.manifestFile.json\n\n# One or more manifests\nfiles: |\n  one.manifest.File.json\n  two.manifest.File.yml\n```\n\nThe `arch` input must be set if building for a non-`x86-64` architecture, like\n`aarch64`. See [Multiple Architectures](#multiple-architectures) for more\ninformation.\n\nThe `gpg-sign` input corresponds to the `--gpg-sign` command-line option and\nshould be a GPG key fingerprint. See [GPG Signing](#gpg-signing) for more\ninformation.\n\nThe `cache-key` input is used as a base to generate cache keys for the\nrepository and build directories. The key can be rotated if the repository\nbecomes too large or needs to be reset for some other reason.\n\n### Deployment Options\n\nFor more information about deploying Flatter, see [Deployment](#deployment).\n\n| Name                    | Default   | Description                            |\n|-------------------------|-----------|----------------------------------------|\n| `upload-bundles`        | `false`   | Upload a bundle for each application   |\n| `upload-pages-artifact` | `false`   | Upload the repo for GitHub Pages       |\n| `upload-pages-includes` | None      | Files to include in GitHub Pages       |\n\nThe `upload-bundles` input controls whether a Flatpak bundle will be uploaded\nwhen an application is built. See [Flatpak Bundles](#flatpak-bundles) for more\ninformation.\n\nThe `upload-pages-artifact` input controls whether the repository will be\nuploaded as a GitHub Pages artifact. See [GitHub Pages](#github-pages) for more\ninformation.\n\nThe `upload-pages-includes` input allows including additional files in the\nGitHub Pages artifact, such as a `index.html`. See [GitHub Pages](#github-pages)\nfor more information.\n\n### Test Options\n\nFlatter supports an opinionated test runner, dynamically rewriting Flatpak\nmanifests to accommodate a testing environment, including a D-Bus session and\nX11 server. The intention is that a Flatpak manifest can be passed for testing\nin a CI, then passed for distribution as a nightly build if successful.\n\n| Name                    | Default   | Description                            |\n|-------------------------|-----------|----------------------------------------|\n| `run-tests`             | `false`   | Override for the manifest's value      |\n| `test-config-opts`      | None      | Options for `meson setup`              |\n| `test-modules`          | None      | Manifest of test dependencies          |\n\nThe `run-tests` input overrides the manifest field of the same name, instructing\n`flatpak-builder` to run `ninja test` once the project is built. If this input\nis `true`, the repository cache will not be used.\n\nThe `test-config-opts` input is a list of extra options to pass to `meson setup`\nfor the target application, used for options like `-Dtests=true`.\n\nThe `test-modules` input is a path to a manifest of extra dependencies, relative\nto the application manifest. This is a convenient way to keep test dependencies\nseparate from release dependencies.\n\n### Advanced Options\n\nFor advanced use cases, extra command-line options can be passed to `flatpak`\nand `flatpak-builder`.\n\n| Name                        | Default | Description                          |\n|-----------------------------|---------|--------------------------------------|\n| `flatpak-builder-args`      | None    | Options for `flatpak-builder`        |\n| `flatpak-build-bundle-args` | None    | Options for `flatpak build-bundle`   |\n\nThe `flatpak-builder-args` input is a multi-line string of options to pass to\n`flatpak-builder`:\n\n```yml\nflatpak-builder-args: |\n  --default-branch=nightly\n  --skip-if-unchanged\n```\n\nThe following options are set internally for `flatpak-builder`:\n\n* `--arch`\n* `--ccache`\n* `--disable-rofiles-fuse`\n* `--force-clean`\n* `--gpg-sign`\n* `--repo`\n* `--state-dir`\n\nThe `flatpak-build-bundle-args` input is a multi-line string of options to pass\nto `flatpak build-bundle`:\n\n```yml\nflatpak-build-bundle-args: |\n  --runtime-repo=https://platform.io/platform.flatpakrepo\n```\n  \nThe following options are set internally for `flatpak build-bundle`:\n\n* `--arch`\n* `--gpg-sign`\n\n## Outputs\n\nThe only output is `repository`, currently.\n\n| Name                    | Description                                        |\n|-------------------------|----------------------------------------------------|\n| `repository`            | Absolute path to the Flatpak repository            |\n\nThe `repository` output is an absolute path to the repository directory,\ncorresponding to the `--repo` command-line option.\n\n## Containers\n\u003e Feel free to open a pull request for additional runtimes\n\nFlatter provides containers with pre-installed runtimes for several platforms,\nbuilt from the base [`Dockerfile`](Dockerfile):\n\n| Image Name               | Version Tags                | Architectures       |\n|--------------------------|-----------------------------|---------------------|\n| `freedesktop`            | `23.08`, `24.08`            | `x86_64`, `aarch64` |\n| `rust`                   | `23.08`, `24.08`            | `x86_64`, `aarch64` |\n| `gnome`                  | `47`, `48`, `master`        | `x86_64`, `aarch64` |\n| `gnome-rust`             | `47`, `48`                  | `x86_64`, `aarch64` |\n| `gnome-typescript`       | `47`, `48`                  | `x86_64`, `aarch64` |\n| `gnome-vala`             | `47`, `48`                  | `x86_64`, `aarch64` |\n| `kde`                    | `5.15-23.08`, `6.6`, `6.7`  | `x86_64`, `aarch64` |\n| `workbench`\u003csup\u003e1\u003c/sup\u003e  | `master`                    | `x86_64`, `aarch64` |\n\n\u003csup\u003e**1** This is custom container for Workbench, based on GNOME Nightly with\nmany language extensions installed by default.\u003c/sup\u003e\n\nContainers are referenced in the form `ghcr.io/andyholmes/flatter/\u003cimage\u003e:\u003ctag\u003e`,\nsuch as `ghcr.io/andyholmes/flatter/gnome:master`:\n\n```yml\nname: Flatter\n\non:\n  # Rebuild once a day\n  schedule:\n    - cron: \"0 0 * * *\"\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n```\n\n## GPG Signing\n\n\u003e [!TIP]\n\u003e If the workflow is intended to be run on pull requests from contributors, be\n\u003e sure to add `if: ${{ github.event_name != 'pull_request' }}` to the GPG\n\u003e signing step to avoid the job failing.\n\nFlatter supports signing the repository and bundles with GPG. First generate a\nGPG key for your repository:\n\n```sh\nmkdir flatter\ngpg2 --homedir flatter --quick-gen-key username@github.io\n```\n\nExport the private key, then add the key and passphrase as GitHub Action secrets\n(e.g. `GPG_PRIVATE_KEY` and optionally `GPG_PASSPHRASE`):\n\n```sh\ngpg2 --homedir flatter --armor --export-secret-key username@github.io\n```\n\n[`crazy-max/ghaction-import-gpg`][gpg-action] can be used to easily import and\npreset the passphrase for signing:\n\n```yml\nname: Flatter (Signed)\n\non:\n  # Rebuild once a day\n  schedule:\n    - cron: \"0 0 * * *\"\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n\n      - name: Setup GPG\n        # Skip GPG signing for pull requests\n        if: ${{ github.event_name != 'pull_request' }}\n        id: gpg\n        uses: crazy-max/ghaction-import-gpg@v5\n        with:\n          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}\n          passphrase: ${{ secrets.GPG_PASSPHRASE }}\n\n      - name: Build\n        uses: andyholmes/flatter@main\n        with:\n          files: |\n            build-aux/flatpak/com.example.App.json\n          gpg-sign: ${{ steps.gpg.outputs.fingerprint }}\n```\n\n[gpg-action]: https://github.com/crazy-max/ghaction-import-gpg\n\n## Deployment\n\nFlatpak repositories generated by `flatpak-builder` are deployable as static\nassets, so deployment is quite flexible.\n\n### Flatpak Bundles\n\nFor each manifest built, Flatter can bundle and upload the application as a job\nartifact. The artifacts are consistently named in the form\n`\u003capplication-id\u003e-\u003carchitecture\u003e` (e.g. `com.example.App-x86_64`).\n\nSet the `upload-bundles` input to `true` and together with\n[nightly.link](https://nightly.link), you can get static links to the most\nrecent Flatpak bundle built by Flatter.\n\n### GitHub Pages\n\n\u003e [!CAUTION]\n\u003e Projects hosted on Github pages may have download speeds throttled if too\n\u003e many users are subscribed to the Flatpak repository.\n\nFlatter can upload the repository as an artifact compatible with GitHub Pages,\nmaking the pages for the GitHub repository a Flatpak Repository.\n\nWhen `upload-pages-artifact` is `true`, Flatter will generate an\n`index.flatpakrepo` file in the repository directory, before preparing the\nartifact. Other files can be added with the `upload-pages-includes` input\n(e.g.`index.html`).\n\nIf the current directory includes a `CNAME` file the contents will be used as\nthe `Url` field, otherwise GitHub's default deployment path will be used\n(e.g. `https://andyholmes.github.io/flatter`).\n\n1. Set the `upload-pages-artifact` input to `true`\n2. In the **Settings** for the GitHub repository, select **Pages** in the\n   sidebar and set **Source** to \"GitHub Actions\"\n3. Add a job with [`actions/deploy-pages`][deploy-pages] to the workflow\n\n```yml\nname: Flatter (GitHub Pages)\n\non:\n  # Rebuild once a day\n  schedule:\n    - cron: \"0 0 * * *\"\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n\n      # Generate a CNAME file in current directory\n      - name: Generate CNAME\n        run: |\n          echo \"flatter.andyholmes.ca\" \u003e CNAME\n\n      - name: Build\n        uses: andyholmes/flatter@main\n        with:\n          files: |\n            build-aux/flatpak/com.example.App.json\n          upload-pages-artifact: true\n          upload-pages-includes: |\n            CNAME\n            default.css\n            index.html\n\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    needs: flatter\n    permissions:\n      pages: write\n      id-token: write\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n\n    steps:\n      - name: GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n```\n\n[deploy-pages]: https://github.com/actions/deploy-pages\n\n### Custom Deploy\n\nThe Flatpak repository directory can also be deployed with another action, such\nas [`JamesIves/github-pages-deploy-action`][deploy-custom]. The example below\ntriggers a GitHub Pages deployment by committing the Flatpak repository to the\n`gh-pages` branch as the subfolder `/repo`:\n\n```yml\nname: Flatter (Deploy)\n\non:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ubuntu-latest\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n    permissions:\n      contents: write\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v3\n\n      - name: Build\n        id: flatpak\n        uses: andyholmes/flatter@main\n        with:\n          files: |\n            build-aux/flatpak/com.example.App.json\n\n      - name: Deploy Repository\n        uses: JamesIves/github-pages-deploy-action@releases/v4\n        with:\n          folder: ${{ steps.flatpak.outputs.repository }}\n          target-folder: repo\n```\n\n[deploy-custom]: https://github.com/JamesIves/github-pages-deploy-action\n\n## Multiple Architectures\n\nFlatter supports building packages for `x86_64` and `aarch64` using GitHub's\nnative runners. Currently, each image has runtimes for both architectures\ninstalled.\n\nMultiple architectures can be built in a [job matrix][gh-matrix] or by adding\nmore jobs, but must not run concurrently if they share a repository directory.\nEither use [`max-parallel`][gh-max-parallel] with `matrix` or use a\n[`concurrency` group][gh-concurrency].\n\n```yml\nname: Flatter\n\non:\n  # Rebuild once a day\n  schedule:\n    - cron: \"0 0 * * *\"\n  workflow_dispatch:\n\njobs:\n  flatter:\n    name: Flatter\n    runs-on: ${{ matrix.arch == 'aarch64' \u0026\u0026 'ubuntu-24.04-arm' || 'ubuntu-latest' }}\n    container:\n      image: ghcr.io/andyholmes/flatter/gnome:master\n      options: --privileged\n\n    # A matrix can be used, but must set `max-parallel: 1`\n    strategy:\n      matrix:\n        arch: [x86_64, aarch64]\n      fail-fast: false\n      max-parallel: 1\n\n    steps:\n      # Checkout a repository with Flatpak manifests\n      - name: Checkout\n        uses: actions/checkout@v3\n\n      - name: Build\n        uses: andyholmes/flatter@main\n        with:\n          files: |\n            build-aux/flatpak/com.example.App.json\n          arch: ${{ matrix.arch }}\n```\n\n[gh-concurrency]: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#concurrency\n[gh-matrix]: https://docs.github.com/actions/using-jobs/using-a-matrix-for-your-jobs\n[gh-max-parallel]: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel\n\n## Acknowledgements\n\n* [Flatpak](https://flatpak.org)\n* [`flatpak/flatpak-github-actions`](https://github.com/flatpak/flatpak-github-actions)\n* [`crazy-max/ghaction-import-gpg`](https://github.com/crazy-max/ghaction-import-gpg)\n* [`JamesIves/github-pages-deploy-action`](https://github.com/JamesIves/github-pages-deploy-action)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyholmes%2Fflatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyholmes%2Fflatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyholmes%2Fflatter/lists"}