https://github.com/thepalaceproject/android-ci

Helper scripts for Android App CI Builds
https://github.com/thepalaceproject/android-ci

android ci mobile

Last synced: 2 months ago
JSON representation

Helper scripts for Android App CI Builds

Host: GitHub
URL: https://github.com/thepalaceproject/android-ci
Owner: ThePalaceProject
Created: 2021-05-13T14:54:49.000Z (about 5 years ago)
Default Branch: main
Last Pushed: 2025-07-02T14:37:33.000Z (11 months ago)
Last Synced: 2025-07-23T04:44:31.982Z (11 months ago)
Topics: android, ci, mobile
Language: Shell
Homepage:
Size: 321 KB
Stars: 1
Watchers: 5
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README-implementation.md

Awesome Lists containing this project

README

# From Commits To Android Builds

## Overview

This document attempts to describe the _continuous integration_ processes
that produce Android builds of the Palace application.

## CI Scripts

The CI process is implemented entirely in plain [Bash](https://www.gnu.org/software/bash/),
with a strong emphasis on allowing developers to run the scripts on their local
machines for testing purposes. The scripts are maintained in a single
[source repository](https://www.github.com/ThePalaceProject/android-ci) and are imported by all projects
wishing to use them as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).

The main entry point into the script is the `ci-main.sh` script, and this
is typically executed by a [GitHub Action](https://github.com/features/actions).
Currently, each repository defines an action to be executed on each authenticated
commit, and a separate action to be executed on pull requests.

## CI Execution

The execution of the CI scripts can be divided into two phases: _building_
and _deploying_. The _build_ phase compiles all of the code and runs the
test suite, and the _deploy_ phase uploads the produced binaries to various
different locations depending on the project-specific configuration.
The _deploy_ phase _only_ executes for authenticated commits (and not pull
requests), because deploying usually requires access to credentials and other
secrets, and a malicious pull request from a third party could steal those
secrets. GitHub actions have built-in protections against this, but the CI
scripts are written in an CI-independent manner, and therefore keep
"executing with credentials" and "executing without credentials" strictly
separated. Given that the execution of a build for a pull request is just
a subset of the execution of a build for an authenticated commit, this
document only goes into detail for the authenticated case.

The full execution of the CI workflow is described by the following graph:

![flow.png](flow.png)

## Build

The _build_ phase requires little explanation: It simply executes a
conventional `./gradlew clean assemble test` command to build the code
and execute the test suite. A _credentials_ step is executed that is
actually controlled by a small project-specific script; it's the responsibility
of this script to copy credentials from an external credentials repository
in to any required locations in the project sources before the build can
proceed.

## Deploy

The _deploy_ phase of the build is more complex and is explained over
the following sections.

### -SNAPSHOT Versioning

The CI scripts expect projects to follow the Maven convention of having version
numbers that end in `-SNAPSHOT` denote volatile snapshot versions of
packages. The artifacts for a snapshot version of a package can be updated
and/or removed at any time. Snapshot versions are convenient during development,
but release versions should always be using non-snapshot versions (and, ideally,
be only using non-snapshot versions of any dependencies too).

The CI scripts read the _gradle.properties_ file in the root of the project
being built, and extract a `VERSION_NAME` attribute from the properties. If
this version name ends with `-SNAPSHOT`, the build assumes that the package
being built is a snapshot version, and adjusts the _deploy_ behaviour
accordingly.

### Tagged Commits

If the contents of the current commit are not a [snapshot version](#-snapshot-versioning),
and the commit is [tagged](https://git-scm.com/book/en/v2/Git-Basics-Tagging),
then the CI scripts assume that the package being built should be _released_
formally, and adjusts the _deploy_ behaviour accordingly.

### Neither -SNAPSHOT Nor Tag!

If the contents of the current commit are not a [snapshot version](#-snapshot-versioning),
and the commit isn't [tagged](#tagged-commits), then the CI scripts assume
that someone made a mistake when committing and forgot to change the version
number from the previous release. The CI scripts adjust their behaviour to
only perform a very minimal deployment.

### Error Handling

The _deploy_ phase defers errors to the end of the build. If an individual
step (such as deploying to Maven Central) fails, then all of the steps that
follow will still be executed, but the build as a whole will be marked as failed
at the end of the _deploy_ phase. The reason for this is that deployment
necessarily involves talking to a lot of external systems, and any of those
systems can fail at any time. If the build is allowed to continue in the
face of errors, then this means that the build can be retried manually
until all of the steps have succeeded.

In practice, it seems to be quite rare for any of the deploy steps to fail,
as all of the external systems seem to be generally reliable.

### Maven Central