Publish & Update a Flatpak App in a Repo

This guide walks you through publishing a Flatpak application to your own repository and then pushing updates to it. You’ll learn how to build the app, create a repository, add the build, install it locally for testing, and finally update the repository when you release a new version. Before starting, you need the Flatpak SDK and a working Flatpak manifest (.json or .yml) for your app.

What You’ll Need

• A Linux system with Flatpak installed (flatpak --version).
• The Flatpak builder tool: sudo apt install flatpak-builder (Debian/Ubuntu) or sudo dnf install flatpak-builder (Fedora).
• The Flatpak runtime and SDK matching your manifest (e.g., org.freedesktop.Platform//24.08 and org.freedesktop.Sdk//24.08). Install them with flatpak install flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08.
• A valid manifest file for your application (e.g., com.example.MyApp.json).
• An SSH key or a web server where you’ll host the repository (for remote access).

Step-by-Step

1. Prepare your build directory. Create a clean directory for the build output, for example build-dir. This will contain the compiled app and its metadata.
2. Build the application. Run flatpak-builder --repo=my-repo build-dir com.example.MyApp.json. This compiles the app and stages it in build-dir. The --repo flag tells the builder to also create a repository named my-repo if it doesn’t exist, and to add the build to it.
3. Verify the build. Check for errors in the output. If the build fails, fix the manifest or source issues and re-run. You can also use flatpak-builder --run build-dir com.example.MyApp.json to test the app before installing it.
4. Initialize the repository (if not already done). If you didn’t use --repo in step 2, create a repository with flatpak build-init-repo my-repo. This sets up the OSTree structure for your repo.
5. Add the build to the repository. If you built without --repo, use flatpak build-commit-from --repo=my-repo my-app-branch build-dir. If you used --repo in step 2, the commit is already done. The branch name is usually app/com.example.MyApp/<arch>/stable or similar, depending on your manifest’s branch key.
6. Generate the appstream metadata (optional but recommended). Run flatpak build-update-repo my-repo to update the repository metadata. This is needed after adding or updating any app.
7. Install the app locally for testing. Add the local repository to Flatpak: flatpak remote-add --user my-repo my-repo (or --system for system-wide). Then install: flatpak install --user my-repo com.example.MyApp.
8. Run and verify the installed app. Launch it from your application menu or with flatpak run com.example.MyApp. Check that it works correctly.
9. Publish the repository. Copy the my-repo directory to a web server or a static hosting service (e.g., scp -r my-repo user@server:/var/www/flatpak/). Ensure the server serves the files over HTTP or HTTPS.
10. Add the remote to users. Users can add your remote with: flatpak remote-add --user my-repo https://example.com/flatpak/my-repo.flatpakrepo. You need to provide a .flatpakrepo file that points to your repo. Create one with the following content:

    [Flatpak Repo]
    Title=My Apps
    Url=https://example.com/flatpak/my-repo
    Homepage=https://example.com
    Comment=My Flatpak repository
    Description=Apps from me
    Icon=https://example.com/icon.png

11. Update the app (new version). When you release a new version, edit your manifest (e.g., bump the version field or change the commit/tag in the source). Then rebuild: flatpak-builder --repo=my-repo build-dir com.example.MyApp.json. This will add a new commit to the repository.
12. Update the repository metadata. Run flatpak build-update-repo my-repo to refresh the summary file.
13. Push the updated repository to your server. Upload the entire my-repo directory again, overwriting the old files. Users will see the update the next time they run flatpak update.

Common Mistakes

• Forgetting to update the repository metadata. If you don’t run flatpak build-update-repo, clients may not see the new version.
• Using the wrong branch name. The branch must match what the manifest specifies. Check with flatpak list --runtime or ostree ls in the repo.
• Not cleaning the build directory. Reusing a dirty build directory can cause stale files. Use flatpak-builder --force-clean build-dir ... to start fresh.
• Hosting the repo over plain HTTP. Flatpak requires a secure connection (HTTPS) for production. HTTP works only for local testing.
• Forgetting to add the runtime SDK. If the runtime is not installed, the build fails with a missing runtime error.

Tips

• Use a version control system (like Git) to track your manifest and build scripts.
• Automate the build and publish process with a CI/CD pipeline (e.g., GitHub Actions) to avoid manual steps.
• Sign your repository with GPG for integrity: flatpak build-update-repo --gpg-sign=KEYID my-repo. This prevents tampering.
• Test the update on a clean system before pushing to production.
• Keep your runtime SDK updated to the latest stable version to get security fixes.

Troubleshooting

• Build fails with “runtime not found”. Install the required runtime and SDK: flatpak install flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08 (adjust version as needed).
• App doesn’t appear after install. Check that the branch name is correct and that you installed from the right remote. Use flatpak list to see installed apps.
• Update not showing for users. Ensure you ran flatpak build-update-repo and that the repository files were fully uploaded to the server (including the summary file).
• Error: “remote not found” when adding. Double-check the URL in the .flatpakrepo file and that the server is accessible.
• Permission denied when writing to repo. If using --system, you may need sudo or change ownership of the repo directory.

Frequently Asked Questions

Can I host a Flatpak repo on GitHub Pages?

Yes, GitHub Pages supports static files, and Flatpak repos are just static OSTree data. Upload the repo to a branch and serve it via HTTPS.

Do I need to sign my repository?

Not strictly, but it’s highly recommended. Without a signature, Flatpak will warn users that the repo is not signed. Use flatpak build-update-repo --gpg-sign=KEYID.

How do I remove an app from my repository?

You can’t remove a specific commit, but you can create a new branch without the app and update the repo. Alternatively, delete the repo and recreate it, but that breaks existing installs.

Can I publish updates without rebuilding the whole app?

Yes, if only metadata changed (like the appstream file), you can use flatpak build-commit-from to add a new commit with just the changed files.

What is the difference between --user and --system?

--user installs the app only for the current user, while --system installs it system-wide (requires root). For publishing, use --system for broader access.

How do I set the version number in the manifest?

In the appdata section, set <releases> with a <release version="1.2.3" date="..."/>. This is what users see in software centers.

Related

• Why Python’s ‘is’ Works for Some Integers but Fails for Others
• How to Set Up Apple Cash Card on iPhone
• Assist Senior Using Computer: Step-by-Step Guide