Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,4 @@ node_modules
.gitignore
README.md
.claude
android
34 changes: 34 additions & 0 deletions .github/workflows/android.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Android app

# Compile check for the Android app. The APK users download is the signed
# build committed at public/gitwall.apk, so this workflow only verifies that
# the source still builds and keeps an unsigned artifact for inspection.
on:
push:
branches: [main]
paths: ["android/**"]
pull_request:
paths: ["android/**"]
workflow_dispatch:

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "17"

- uses: gradle/actions/setup-gradle@v4

- name: Build APK
working-directory: android
run: ./gradlew --no-daemon assembleRelease

- uses: actions/upload-artifact@v4
with:
name: gitwall-apk-unsigned-check
path: android/app/build/outputs/apk/release/app-release.apk
10 changes: 10 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,13 @@ node_modules/
out/
.claude/
.gstack/

# Android app
android/.gradle/
android/build/
android/app/build/
android/local.properties
android/keystore.properties
android/*.jks
android/*.keystore
tsconfig.tsbuildinfo
33 changes: 22 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Turn your GitHub contribution graph into a phone wallpaper.
- **Android** support: 70+ devices across Samsung, Google Pixel, OnePlus, Xiaomi, Nothing, Motorola, Sony, ASUS, OPPO, vivo, Realme, and Honor
- Shows contribution stats: total count and current streak
- iOS Shortcut-compatible URL for daily auto-updating wallpapers (iPhone)
- MacroDroid-compatible URL for daily auto-updating wallpapers (Android)
- GitWall Android app (`android/`) that sets the lock screen from the same URL and refreshes daily
- In-memory caching with 5-minute TTL

## Setup
Expand Down Expand Up @@ -45,14 +45,15 @@ npm run build
npm start
```

Open `http://localhost:3000`, enter a GitHub username, pick your platform (iPhone or Android), choose a theme and device, and download your wallpaper.
Open `http://localhost:3000`, enter a GitHub username, pick your platform (iPhone or Android), choose a theme, and download your wallpaper.

### API Endpoints

| Endpoint | Description |
|---|---|
| `GET /api/wallpaper?user=<username>` | Full-resolution wallpaper PNG (iPhone) |
| `GET /api/wallpaper?user=<username>&width=1440&height=3120` | Full-resolution wallpaper PNG (Android) |
| `GET /api/wallpaper?user=<username>&width=1080&height=2340` | Wallpaper PNG at an exact size (used by the Android app) |
| `GET /download/android` | Redirects to the Android APK (`/gitwall.apk`) |
| `GET /api/preview?user=<username>` | Low-res preview PNG |
| `GET /api/themes` | List available themes |
| `GET /api/devices` | List supported iPhone devices |
Expand All @@ -71,15 +72,25 @@ The API returns proper status codes: `400` for a missing or malformed username,
4. Add **Set Wallpaper** using the result
5. Automate it: Automation → Time of Day → run daily

**Android (MacroDroid)**
1. Generate your wallpaper, select your phone model, and copy the MacroDroid URL
2. Install [MacroDroid](https://play.google.com/store/apps/details?id=com.arlosoft.macrodroid) from Google Play
3. Add Macro → Trigger: Date/Time → Daily at 00:01
4. Action 1: HTTP Request (GET) → save response to `/Download/gitwall.png`
5. Action 2: Device Settings → Set Wallpaper → `/Download/gitwall.png`
6. Name the macro and tap **Create Macro**
**Android (GitWall app)**
1. Generate your wallpaper and copy the URL (no phone model needed)
2. Install the GitWall app from the website's **Download APK** button (`/download/android`)
3. Tap **Open in GitWall app**, or paste the URL into the app
4. Tap **Set lock screen wallpaper**. The app appends your phone's real resolution, sets the lock screen directly through Android's wallpaper API, and refreshes daily at a time you pick (06:00 by default)

> Use the **exact same filename** in both actions.
Task-automation apps such as MacroDroid cannot do this reliably: Android copies wallpapers into private system storage, so replacing a file on disk never changes the lock screen, and newer Android versions block writes to shared folders.

### Android app

The app lives in `android/` (Kotlin, Jetpack Compose, WorkManager, minSdk 26).

```bash
cd android
./gradlew assembleDebug # android/app/build/outputs/apk/debug/app-debug.apk (allows plain http for local testing)
./gradlew assembleRelease # signed when android/keystore.properties exists
```

The signed release APK is committed as `public/gitwall.apk` and served by the website at `/gitwall.apk`. To ship a new version, bump `versionCode` and `versionName` in `android/app/build.gradle.kts`, rebuild with the same keystore, and replace that file. `keystore.properties` (git-ignored) holds `storeFile`, `storePassword`, `keyAlias`, `keyPassword`; the keystore must stay the same across releases or existing installs cannot update. Set `ANDROID_APK_URL` to point `/download/android` elsewhere when self-hosting.

## Tech Stack

Expand Down
83 changes: 83 additions & 0 deletions android/app/build.gradle.kts
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
import java.util.Properties

plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("org.jetbrains.kotlin.plugin.compose")
}

// Release signing is read from android/keystore.properties (git-ignored) or from
// the environment in CI. Without either, the release build falls back to the
// debug key so a local test build always succeeds.
val keystoreProps = Properties().apply {
val f = rootProject.file("keystore.properties")
if (f.exists()) f.inputStream().use { load(it) }
}
fun signingValue(key: String): String? =
keystoreProps.getProperty(key) ?: System.getenv("GITWALL_${key.uppercase()}")

android {
namespace = "space.gitwall.app"
compileSdk = 35

defaultConfig {
applicationId = "space.gitwall.app"
minSdk = 26
targetSdk = 35
versionCode = 1
versionName = "1.0.0"
}

signingConfigs {
val storeFile = signingValue("storeFile")
if (storeFile != null) {
create("release") {
this.storeFile = rootProject.file(storeFile)
storePassword = signingValue("storePassword")
keyAlias = signingValue("keyAlias")
keyPassword = signingValue("keyPassword")
}
}
}

buildTypes {
release {
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
signingConfig = signingConfigs.findByName("release") ?: signingConfigs.getByName("debug")
}
}

compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}

buildFeatures {
compose = true
}

packaging {
resources.excludes += setOf("META-INF/*.version", "kotlin/**", "DebugProbesKt.bin")
}
}

dependencies {
val composeBom = platform("androidx.compose:compose-bom:2024.12.01")
implementation(composeBom)

implementation("androidx.core:core-ktx:1.15.0")
implementation("androidx.activity:activity-compose:1.9.3")
implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.7")
implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7")
implementation("androidx.work:work-runtime-ktx:2.10.0")

implementation("androidx.compose.ui:ui")
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.material3:material3")
implementation("androidx.compose.material:material-icons-core")
}
2 changes: 2 additions & 0 deletions android/app/proguard-rules.pro
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# WorkManager instantiates workers reflectively by class name.
-keep class space.gitwall.app.RefreshWorker { *; }
6 changes: 6 additions & 0 deletions android/app/src/debug/AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Debug builds only: allow plain http so the app can be tested against a
local `npm run dev` server. Release builds stay https-only. -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application android:usesCleartextTraffic="true" />
</manifest>
40 changes: 40 additions & 0 deletions android/app/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.SET_WALLPAPER" />

<application
android:allowBackup="false"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/Theme.GitWall">

<activity
android:name=".MainActivity"
android:exported="true"
android:launchMode="singleTask"
android:windowSoftInputMode="adjustResize">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

<!-- gitwall://setup?url=<encoded wallpaper URL>, opened from the website -->
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="gitwall" android:host="setup" />
</intent-filter>

<!-- Share a wallpaper URL to the app from any browser -->
<intent-filter>
<action android:name="android.intent.action.SEND" />
<category android:name="android.intent.category.DEFAULT" />
<data android:mimeType="text/plain" />
</intent-filter>
</activity>
</application>
</manifest>
Loading
Loading