Doing this is apparently the best way to get your own package into the repository, since you can provide a direct merge request for the metadata about your package, making it easy for the maintainers.

To understand the overview of the process, read the Proposal by Metadata Merge Request section of the Inclusion How-To.

First steps

In the source of the application you want to include, find all the AndroidManifest.xml and build.gradle files, and write down in which subdir the most detailed of them happen to be.

Register on GitLab and fork the fdroiddata repository.

Upstream metadata

Each official release commit in the application’s upstream Git repository should have a tag. For example, if its AndroidManifest contains versionName: '1.0', the commit needs a v1.0 tag. It is strongly encouraged to add metadata in the application’s source repo, too:

• fastlane/metadata/android/en-US/short_description.txt (less than 80 characters, no trailing dot)
• fastlane/metadata/android/en-US/full_description.txt
• fastlane/metadata/android/en-US/images/icon.png
• fastlane/metadata/android/en-US/images/phoneScreenshots/1.png
• fastlane/metadata/android/en-US/images/phoneScreenshots/2.png

If the AndroidManifest contains versionCode: 123, there should be a corresponding explanation of what’s new in this version:

• fastlane/metadata/android/en-US/changelogs/123.txt (max 500 characters)

Browse the F-Droid client metadata directory to see a real-world example.

Other formats and locations of the description, graphics, and screenshots are supported, too. For example, the metadata/en-US directory can instead be fastlane/metadata/android/en-US.

Send the application’s development team a merge request if the repository doesn’t have those files, and open an issue if it has no version tags. Having this metadata in place lets it be under direct control of the developer, and their updates and future translations will be pulled automatically.

Build environment

On a laptop with Ubuntu 21.10 in February 2022, it took 2 GB of traffic and 5 GB of disk space to set up an F-Droid build environment.

Network requirements:

• 60 MB: shallow-clone fdroiddata and fdroidserver
• 75 MB: install docker.io
• 1000 MB: load the container
• 800 MB: build

Storage requirements:

• 1000 MB: clone the repos and install docker.io
• 4000 MB: load the container and build

Download your fork, then create a new branch and a metadata file. For example, if the application’s build.gradle says applicationId "com.example":

git clone --depth=1 https://gitlab.com/YOUR_ACCOUNT/fdroiddata ~/fdroiddata
cd ~/fdroiddata
git checkout -b com.example
cp templates/build-gradle.yml metadata/com.example.yml

Fill ~/fdroiddata/metadata/com.example.yml according to the build metadata reference. If you have convinced the application’s development team to include the descriptions and use version tags in their repository as explained above, the file will be very concise:

Categories:
  - Internet
  - Navigation
License: GPL-3.0-or-later
# Add info about you and the App so that the user can know the App and its author better
AuthorName: FOSS Lover
AuthorEmail: fosslover@f-droid.org
WebSite: https://example.f-droid.app
SourceCode: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom
IssueTracker: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom/-/issues

RepoType: git
Repo: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom
Binaries: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom/-/releases/v%v/downloads/app-release.apk

Builds:
  - versionName: '1.0'
    versionCode: 123
    # Use the commit hash which the App should be built from
    commit: deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
    # Where build.gradle is:
    subdir: app
    sudo:
      # see text below
      - echo "deb https://deb.debian.org/debian trixie main" > /etc/apt/sources.list.d/trixie.list
      - apt-get update
      - apt-get install -y -t trixie openjdk-21-jdk-headless
      - update-alternatives --auto java
    gradle:
      - yes

# Extract from your signed APK with `apksigner verify --print-certs`
AllowedAPKSigningKeys: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

AutoUpdateMode: Version
UpdateCheckMode: Tags
CurrentVersion: '1.0'
CurrentVersionCode: 123

Adjust or remove the relevant sudo lines if needed, eg:

• The example application requires JDK 21, so we install openjdk-21-jdk-headless from the official Debian repositories. The Debian version and default packages installed on F-Droid’s buildserver can be found in https://gitlab.com/fdroid/fdroidserver/-/blob/master/buildserver/provision-apt-get-install.

Download and launch the latest version of the server tools container:

git clone --depth=1 https://gitlab.com/fdroid/fdroidserver ~/fdroidserver
sudo sh -c 'apt-get update &&apt-get install -y docker.io'
sudo docker run --rm -itu vagrant --entrypoint /bin/bash \
  -v ~/fdroiddata:/build:z \
  -v ~/fdroidserver:/home/vagrant/fdroidserver:Z \
  registry.gitlab.com/fdroid/fdroidserver:buildserver

In the container:

. /etc/profile
export PATH="$fdroidserver:$PATH" PYTHONPATH="$fdroidserver"
export JAVA_HOME=$(java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home' | awk -F'=' '{print $2}' | tr -d ' ')
cd /build
fdroid readmeta
fdroid rewritemeta com.example
fdroid checkupdates --allow-dirty com.example
fdroid lint com.example
fdroid build com.example

If any command, such as fdroid readmeta, returns an error, edit ~/fdroiddata/metadata/com.example.yml accordingly and try running the command again. After a successful build, exit the container, commit your metadata file with a New App label, and push it to your fork:

exit
cd ~/fdroiddata
git add metadata/com.example.yml
git commit -m "New App: com.example"
git push origin com.example

Create a merge request at the fdroiddata repository, selecting your com.example source branch. Wait for the packagers to pick up your merge request. Please keep track if they asked any questions and reply to them as soon as possible.

Troubleshooting

You can get help with F-Droid via IRC, Matrix, XMPP, e-mail and some other channels.