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:

• metadata/en-US/short_description.txt (30-50 chars, no trailing dot)
• metadata/en-US/full_description.txt
• metadata/en-US/images/icon.png
• metadata/en-US/images/phoneScreenshots/screenshot.png

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

• metadata/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
SourceCode: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom

RepoType: git
Repo: https://gitlab.com/APPLICATION_UPSTREAM/ExampleCom

Builds:
  - versionName: '1.0'
    versionCode: 123
    commit: v1.0
    # Where build.gradle is:
    subdir: app
    sudo:
      - apt-get update
      - apt-get install -y librsvg2-bin openjdk-17-jdk-headless
      - update-alternatives --auto java
    gradle:
      - yes

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

Adjust or remove the relevant sudo lines if needed:

• The example application’s build.gradle executes rsvg-convert to rasterize its vector icons, so we install librsvg2-bin from the official Debian repositories. All such dependencies should be specified in the app’s README.

• gradle/wrapper/gradle-wrapper.properties mentions gradle-8.0, and Gradle 8 is known to depend on Java 17. So we install openjdk-17-jdk-headless and select it as the java alternative.

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.