Submitting Apps to the Marketplace

Want your app in the Companion App Store? You can submit through our web form or open a pull request to the marketplace repository.

Prerequisites

The app must run as a Docker container
A public or submit-able Docker image — or build one with the Static Container Builder
A GitHub account, if you submit by pull request

Submit via the web form (recommended)

Visit ci.computer/store-submit and complete the submission form. You’ll need the same files described below: a config.json manifest, a docker-compose.json, a metadata/ folder, and a README.

After review, approved apps appear in the App Store for all Hub users.

App folder structure

Each app lives in apps/<slug>/ in the CI-Marketplace repository. Use Nextcloud as a reference implementation:

- config.json
- docker-compose.json
- - description.md
  - logo.png
- README.md

Required files

File	Purpose
`config.json`	Metadata, form fields, categories, Hub integration — see the config.json reference
`docker-compose.json`	Service definition (preferred) or legacy `docker-compose.yml`
`metadata/description.md`	Long description for the App Store detail page
`metadata/logo.png`	Square logo (~256×256 px)
`README.md`	Developer docs for reviewers

`config.json`

Required metadata: name, id, port, categories, form_fields, supported_architectures, and more. Use cihub_app_version (not the legacy tipi_version) and set dynamic_config: true for new apps.


{
  "name": "Nextcloud",
  "id": "nextcloud",
  "available": true,
  "short_desc": "A safe home for all your data.",
  "author": "nextcloud",
  "port": 8301,
  "categories": ["data", "featured"],
  "description": "Nextcloud is a suite of client-server software...",
  "version": "latest",
  "source": "https://github.com/nextcloud/server",
  "website": "https://nextcloud.com",
  "exposable": true,
  "supported_architectures": ["arm64", "amd64"],
  "dynamic_config": true,
  "form_fields": [
    {
      "type": "random",
      "label": "Database Password",
      "min": 32,
      "env_variable": "NEXTCLOUD_DB_PASSWORD"
    },
    {
      "type": "text",
      "label": "Admin User",
      "default": "admin",
      "required": true,
      "env_variable": "NEXTCLOUD_ADMIN_USER"
    }
  ],
  "cihub_app_version": 10
}

`docker-compose.json`

Dynamic compose (schema version 2) is the current format. Define services, internal ports, volumes, health checks, and environment variable references:


{
  "schemaVersion": 2,
  "services": [
    {
      "name": "nextcloud",
      "image": "nextcloud:latest",
      "internalPort": 80,
      "isMain": true,
      "volumes": [
        {
          "hostPath": "${APP_DATA_DIR}/data/nextcloud",
          "containerPath": "/var/www/html"
        }
      ],
      "environment": [
        { "key": "POSTGRES_PASSWORD", "value": "${NEXTCLOUD_DB_PASSWORD}" }
      ]
    }
  ]
}

See Dynamic Compose for the full schema.

`metadata/description.md`

Long-form description shown on the app’s detail page in the App Store. Supports Markdown/HTML.

`metadata/logo.png`

Square logo (recommended 256×256 px). Displayed in the App Store grid and app detail page.

`README.md`

Developer-facing documentation: what the app does, required env vars, architecture notes, and testing instructions for reviewers.

Building your container

You have two paths:

Use an existing Docker image

If your app already publishes to Docker Hub or GHCR, reference that image in docker-compose.json. This is the fastest path for standard open-source apps.

Build with Static Container Builder

For static sites and front-ends without a public image, use the Static Container Builder — a Dockerfile that bakes your built assets into a hermetic nginx image:


docker build --build-arg STATIC_FILES_PATH=./dist -t my-app .

Push the resulting image to a registry (Docker Hub or GHCR) and reference it in your docker-compose.json.

There is no ci-builder CLI. Earlier versions of these docs described ci-builder init/build/package commands that do not exist — use docker build as shown above.

AI-enabled apps

If your app uses LLMs, add hub_integration.inference to map Hub-resolved AI variables into your app’s env. See AI & Inference.

Agent apps that talk to Hub MCP should set hub_integration.mcp_client: true.

Submit via pull request

Alternatively, fork CI-Marketplace , add your app under apps/<slug>/, and open a PR. Follow the same folder structure and test locally with a custom app store.

Test locally

Add your repo as a custom app store in Hub (Settings → App Stores → Add), then install your app from the store.

Open a PR

Include screenshots or a short screen recording of a successful install. Set supported_architectures accurately — Hub hides apps that don’t match the host CPU.

Review

Maintainers verify the app installs cleanly, uses official images where possible, and follows security best practices (no hardcoded secrets, sensible defaults).

First submission? Publish your first app walks the four required files in order, and is candid about where local testing currently stands.

Guidelines

Prefer official upstream Docker images
Provide sensible defaults; use random form fields for passwords and secrets
Declare min_hub_version if your app needs a recent Hub feature
Set supported_architectures accurately, and test on both amd64 and arm64 if you claim both
Test a clean install on a fresh Hub instance before submitting
Do not bundle telemetry or phone-home behaviour without disclosure

Questions about submissions? Visit ci.computer or open a discussion on the marketplace repository.