Repotool

Usage

How to use Repotool.

Initial setup

Repotool requires a certain directory structure set up to process data and create a repository out of it.

To get the most out of Repotool, please also check the configuration options.

These are example steps to show how this can be done.

Prepare a working directory

This is where the Repotool data will live in, in this example this is ~/repotool.

Terminal

mkdir ~/repotool
cd ~/repotool

Create the configuration files

A configuration file allows you to customize the behavior of Repotool, let it know about your data, etc.

Initially create the configuration file for the CLI. For now all it contains is the path to the configuration file for the Repotool itself.

Terminal

echo 'repotool_config_file_path: "repotool.yaml"' > repotool-cli.yaml

Next create the configuration file for the Repotool.

Repotool uses defaults for a directory structure, which can be customized if needed. For our example, we are not touching them though and keep the defaults.

A java keystore will be used for signing operations. You can either use your existing one or let Repotool create a new one. In any case, you need to configure it, as seen below, filling in your own data.

Terminal

cat > repotool.yaml<< EOF
keystore:
  keystore_path: "repo/katastima.p12"
  keystore_password: "changeme"
  key_alias: "katastima.org"
  key_password: "changeme"
  key_subject_line: "C=AT, ST=Kärnten, L=Wolfsberg, O=Katastima, OU=Katastima, CN=katastima.org, emailAddress=katastima@katastima.org"
EOF

After configuring your keystore, add some basic information about your repository to the same config file.

Terminal

cat >> repotool.yaml<< EOF
repo:
  name: "Katastima Repository"
  description: "TODO: change me, please"
  address: "https://katastima.org/repo"
EOF

For address, use the URL where you are going to host your repository.

The current setup should like this:

Terminal

$> tree
.
├── repotool-cli.yaml
└── repotool.yaml

You can also verify your config is picked up correctly using repotool config show:

Terminal

~/repotool/repotool-cli.yaml:
verbose: false
quiet: false
repotool_config_file_path: "repotool.yaml"
console_output:
  enable_rich_output: true

~/repotool/repotool.yaml:
data:
  assets_directory_path: "repo/assets"
  build_directory_path: "repo/build"
  git_directory_path: "repo/git"
  metadata_directory_path: "repo/metadata"
  plugin_directory_path: "plugins"
  repo_directory_path: "repo/repo"
  repo_icons_directory_path: "repo/repo/icons"
  temporary_directory_path: "repo/tmp"
keystore:
  keystore_path: "repo/katastima.p12"
  keystore_password: "changeme"
  key_alias: "katastima.org"
  key_password: "changeme"
  key_subject_line: "C=AT, ST=Kärnten, L=Wolfsberg, O=Katastima, OU=Katastima, CN=katastima.org,\
    \ emailAddress=katastima@katastima.org"
repo:
  version: 30000
  name: "Katastima Repository"
  icon: "icon.png"
  address: "https://katastima.org/repo"
  description: "TODO: change me, please"
  frontendAddress: null
  mirrors: null
plugins:
  expose_loaded_plugins: false

Prepare your repository data

This is a huge topic in its own, for more information see the repository structure.

To be able to follow along the guide, we are creating a simple binary repository, containing Catima.

First the metadata structure and recipe needs to be created.

Terminal

# Create the metadata directory
mkdir -p repo/metadata

# Add the recipe for Catima, taken from https://codeberg.org/IzzyOnDroid/repodata/src/commit/8805e21487c7c01e58d5faf63d887f1c104133dd/metadata/me.hackerchick.catima.yml
cat > repo/metadata/me.hackerchick.catima.yml<< EOF
Categories:
  - Money
License: GPL-3.0-or-later
AuthorName: Sylvia van Os
SourceCode: https://github.com/CatimaLoyalty/Android
IssueTracker: https://github.com/CatimaLoyalty/Android/issues
Translation: https://hosted.weblate.org/projects/catima/catima/
Changelog: https://github.com/CatimaLoyalty/Android/blob/HEAD/CHANGELOG.md
AutoName: Catima

MaintainerNotes:
  AppAdded: 2020-11-01
  Method: github-release
  GHSkipPre: 1
  Fastlane: https://github.com/CatimaLoyalty/Android/tree/main/fastlane/metadata/android
  FastlaneFeatures: title,shortdesc,fulldescMD,changelogs,icon,featureGraphic,screenshotsJPG
  LibIgnore:
    - /org/acra
  PermIgnore:
    android.permission.CAMERA: needed to scan Barcodes
    android.permission.READ_EXTERNAL_STORAGE: needed on Android 6 and below to create or import backups. You can safely deny this permission, but then you’ll not be able to create or import backups
  DoubleList: keep
  DoubleListRef: https://github.com/CatimaLoyalty/Android/issues/82#issuecomment-730407962
  NameSpaces:
    - /protect/card_locker

AllowedAPKSigningKeys: d405cd69ede4c22074c328fb825689a84ab3fca4b3fdf0b6cc1333af62c67eb3

AutoUpdateMode: Version v%v
UpdateCheckMode: Tags
EOF

You will also need to add an APK file of the app, which you have added a recipe for previously.

Terminal

# Create the repo directory, which will contain APK files as well as the generated repo.
mkdir -p repo/repo

# Download the latest catima release from github.
# Note: usually you want to store your APKs as `packagename_versioncode.apk` but we keep this example generic and simple.
wget -O repo/repo/catima.apk https://github.com/CatimaLoyalty/Android/releases/latest/download/app-foss-release.apk

You also have to provide a repository icon, as Repotool is not providing a default icon at the time of writing.

When following this guide, you can do the following to provide it:

# Create the assets directory, where the repo icon will be stored.
mkdir -p repo/assets

# Download the Katastima icon.
wget -O repo/assets/icon.png https://codeberg.org/Katastima/repotool/raw/commit/70df3e3d3eb3aabd755dbadb5a37930febd66e88/data/icon.png

Update metadata

Whenever you are doing changes to your metadata you need to update it using repotool metadata update.

This step will check the metadata directory for app recipes and if it has found any, fetch the git repository associated with the app recipe for further processing (e.g.: running verification checks, process the fastlane metadata, etc.).

repotool metadata update

Started preparing
Finished preparing
Finished fetching: Fetched 1 repositories
Finished processing: Processed 1 repositories

Generate the repository

To generate the repository, use repotool repo update.

This step needs to be repeated whenever you have modified and updated your metadata as well as when adding or removing APK files.

repotool repo update

Started parsing
Started parsing APKs
Finished parsing APKs
Finished parsing
Started generating repo information
Finished generating repo information
Started generating repo assets
Finished generating repo assets
Started generating index-v1
Finished generating index-v1
Started generating index-v2
Finished generating index-v2

You can now take repo/repo and host it at the address specified in your configuration (repo > address).

Advanced usage

Specify path to CLI config file

You can use -c/--config to specify a custom location for the repotool-cli.yaml (defaults to current working directory where you run repotool).

Terminal

repotool -c /path/to/repotool-cli.yaml

repotool --config /path/to/repotool-cli.yaml

`argfile` support

Loading additional CLI arguments from a file is supported.

To use it, pass in any file path prefixed with @ to expand the contents of the file into command line parameters.

-q
metadata
update

repotool @update_metadata.shell

repotool \
  -q \
  metadata \
  update

Installation

A guide to install Repotool.

Configuration

How to configure Repotool using configuration files.