F-Droid

Overview

The Bitwarden F-Droid repository is hosted on GitHub. It contains all Bitwarden apps that are available on F-Droid.

The Bitwarden F-Droid repository is automatically updated periodically to ensure the apps hosted in the repository are up to date with the latest versions released in the Google Play Store.

Setup

Go

Go is required to build and run the metascoop app.

To download and install Go with Homebrew run :

brew install go

Other download and installation options can be found on the Go installation documentation.

F-Droid server and repo tools

To manually update the F-Droid repository, F-Droid server and repo tools are required. Installation instructions can be found on the official F-Droid server and repo tools documentation.

Android SDK

F-Droid Server and Repo Tools requires apksigner, which is part of the Android SDK.

To install the required Android SDK tools using Homebrew run:

brew install android-sdk
android update sdk --no-ui --all --filter tools,platform-tools,build-tools-25.0.0

Alternate instructions for downloading and installing the required Android SDK tools can be found here.

File Structure

The repository is organized into the following structure:

• fdroid/: The F-Droid repository where applications are hosted.
• metascoop/: The Go app used to update the F-Droid repository when a new version of a Bitwarden app is released.
• repos.yml: The file that defines the source repositories and F-Droid applications available to be hosted.

repos.yml

This file contains details about the source repositories that metascoop will search for new F-Droid releases. It uses the following structure to declare repositories and their applications:

my-repository:
  git: "https://github.com/bitwarden/android"
  applications:
    - filename: "com.x8bit.bitwarden-fdroid.apk"
      id: "bitwarden"
      name: "Bitwarden"
      categories:
        - Security
      description: |
        My awesome app description.

• my-repository: The name of the repository. This is used to identify the repository in the index.
• git: The URL of the source repository.
• applications: The applications that are available in the repository. Multiple applications can be added to the repository by adding a new entry to the applications list.
  • filename: The name of the APK file that will be downloaded from the source repository.
  • id: The ID of the application. This must be unique and is used to identify the application in the F-Droid repository.
  • name: The name of the application displayed to users when viewing applications in F-Droid.
  • categories: The categories that the application belongs to. This is used to categorize the application in F-Droid.
  • description: The description displayed to users when viewing the application in F-Droid.

metascoop/

Bitwarden's F-Droid repository is configured to automatically update apps when a new version is detected in one of the source repositories defined in repos.yml.

This is done by using the metascoop app to fetch the latest version of the source repository and then update the repository index.

The metascoop app is run periodically by the CI/CD pipeline to ensure the repository index stays up to date.

When changes are detected in the source repository, any new releases will be added to the F-Droid repository, and fdroid update will be executed to update F-Droid server and repo metadata. The CI/CD pipeline will automatically create a pull request to update the repository with these changes.

fdroid/

The majority of files within this directory are generated by the metascoop app and fdroid tools. Some files cannot be automatically generated and must be manually edited.

F-Droid repo configuration

F-Droid repository is configured in a config.yml file. This includes details like the name, description, and archive settings. This file is not tracked for security purposes.

Repository icon

The F-Droid repository icon is stored in fdroid/icon.png.

Application images

Some application metadata, such as the application icons, feature graphics, and screenshots, are not defined in the repos.yml file and must be placed in the correct location within the F-Droid repository.

The following directory structure is used to store the application images:

• fdroid/repo/<app-id>/<locale>/icon.png: The application icon.
• fdroid/repo/<app-id>/<locale>/feature-graphic.png: The feature graphic.
• fdroid/repo/<app-id>/<locale>/<screen-type>Screenshots/*.png: Screenshots from various devices. I.e. fdroid/repo/com.x8bit.bitwarden/en-US/phoneScreenshots/login-screenshot.png.

Details on the metadata file structure can be found in the official F-Droid docs, here.

Testing

Local testing

The run_metascoop.sh and update_repo.sh scripts can be executed to manually check for new releases and update the F-Droid repository. This can be especially helpful for testing.

When executing run_metascoop.sh locally, the repository keystore is required because fdroid update is executed as part of the process.

A temporary keystore can be generated by running fdroid init in the fdroid directory and following the prompts. This will result in the config.yml and keystore.p12 files being generated with default values.

To generate a new keystore and config, run:

cd fdroid
fdroid init

warning

Never push changes signed by a locally generated keystore or config.

Using a locally generated keystore or config forces regeneration of ALL metadata and re-signs the repository. These changes should only be used for local testing.

It's possible to run a local F-Droid server for end-to-end testing. This type of testing requires setting up your machine as a web-server and copying the entire repository into your web root directory. Instructions on setting up a local demo repository can be found in the official F-Droid docs, here.

note

In order to connect to your local repository from an Android emulator use 10.0.2.2 instead of localhost.

MacOS users

If using nginx as the web server, and it is installed using Homebrew the web root is located at /opt/homebrew/var/www/.

To start/stop nginx run:

brew services start nginx
brew services stop nginx

By default, nginx will listen on port 8080 when started from homebrew. An example of the local server URL, when entered from an emulator, should look like: http://10.0.2.2:8080/fdroid/repo

Remote testing

The fdroid.yml workflow can be triggered from the GitHub Actions tab. The workflow can be run without publishing changes by checking the "Dry run" checkbox. Be default, the workflow will publish the changes to the F-Droid repository.

Security

The F-Droid repository is signed with a certificate owned by Bitwarden. Users can verify the validity of the repository by comparing the signature against the fingerprint provided in the README.md file.