Contributing to Colony

Two types of contribution land here, each with a different path:

Adding your app to the Colony catalog — jump to Adding your app to Colony.
Contributing to Colony itself (the launcher) — jump to Contributing to Colony itself.

Adding your app to Colony

Colony automatically scans all public repositories under the Project-Colony GitHub organization. A repo becomes a Colony app when:

A colony.json manifest sits at the repo root.
A GitHub release exists with assets matching the naming convention below.

Step 1 — Prepare a `colony.json`

Minimal form:

{
  "name": "YourApp",
  "category": "Utilities"
}

Valid categories: Development, Graphics, Network, Office, Multimedia, System, Utilities, Games, Other.

App icon (recommended): put a square PNG at assets/icons/icon.png and declare it in the manifest — "icon": "assets/icons/icon.png". Colony shows it in the grid; without it your app gets a generated category tile. The same folder is the standard home for your icon.ico (Windows) and icon.icns (macOS). See the App icon section of the spec.

For the full reference (pinned releases, explicit platforms, archive extraction, SHA256, pattern-matched asset names, etc.), read docs/colony-spec.md.

Step 2 — Publish release assets

Colony auto-detects platforms from release asset filenames using the pattern <repo-name-lowercase>-<platform>:

Asset name	Detected platform
`yourapp-linux`	Linux x86_64
`yourapp-windows.exe`	Windows x86_64
`yourapp-macos`	macOS ARM (Apple Silicon)
`yourapp-macos-x86`	macOS Intel

You can upload any subset — Colony only advertises the platforms whose asset is present. Assets can be raw binaries or .zip / .tar.gz archives; see the spec if you archive.

Step 3 — Wire up a release workflow (Rust apps)

A ready-to-use GitHub Actions template is in this repo at .github/workflows/colony-rust-release.yml.template. Copy it to your own repo as .github/workflows/release.yml and replace {{APP_NAME}} with your binary/repo name (lowercase).

It uses release-please so every merged PR tagged with a conventional-commit prefix (feat:, fix:, etc.) opens a release PR; merging that PR tags the version, builds the matrix of 4 platforms, and uploads the assets under the convention above. Zero manual release work afterwards.

Non-Rust apps: replicate the same asset naming convention with whatever tooling you prefer (electron-builder, pyinstaller, go build, etc.).

Step 4 — Get your repo into Project-Colony

Two paths:

Transfer your existing repo into the Project-Colony organization (GitHub → repo Settings → Transfer ownership). Simplest if you're the sole owner.
Fork it under the org if you want to keep the canonical elsewhere. Colony picks up the fork as long as it has colony.json at root and releases with matching assets.

Either way, ping a maintainer (open an issue on Project-Colony/Colony) with your repo URL so they can approve the transfer/fork and confirm detection.

Step 5 — Verify detection

On your machine:

colony   # launch Colony, wait a few seconds for the next catalog refresh

Your app card should appear in the category you declared. If not:

Make sure the release is published (not a draft).
Make sure asset names match the convention (lowercase, no version in the name, correct extension).
Look in ~/.cache/colony/repos_cache.json — if your repo is there but without platforms, the colony.json or the asset names are wrong. See the spec for the precise validation rules.
Verify you aren't hitting the GitHub rate limit: Settings → GitHub → Connect.