Creating Service Providers

Codesphere allows you to publish existing Codesphere landscapes as Managed Service Providers. This enables other developers to discover and deploy your custom solutions.

Landscape-based Service Providers​

A landscape-based service provider enables others to instantiate your Codesphere landscape as a pre-configured managed service that they can deploy and manage through the service catalog.

Prerequisites​

Before creating a landscape-based service provider, you need:

1. A Git repository containing a valid Codesphere landscape with a ci.yml file.
2. A provider definition, either as a provider.yml file at the repository root or provided directly in the API request.
3. Git access to the landscape repository. Codesphere pulls the repository through your Git connection, so the account you use to create the provider must have permission to access it. You can manage your Git connections in your user settings.

For an example, take a look at our public URL-Shortener Repository.

Provider Definition​

The provider.yml file defines all metadata and configuration schemas for your service provider.

name: mattermost
schemaVersion: v1
author: Your Team
displayName: Mattermost
iconUrl: https://example.com/mattermost-icon.png
category: collaboration
description: |
  Open-source team messaging and collaboration platform.
  Supports channels, direct messaging, and file sharing.
teamSingleton: true

backend:
  landscape:
    gitUrl: https://github.com/your-org/mattermost-landscape

configSchema:
  type: object
  properties:
    SITE_NAME:
      type: string
      description: Display name for your Mattermost instance
      default: mattermost
      readOnly: false
    MAX_USERS:
      type: integer
      description: Maximum number of users allowed
      x-update-constraint: increase-only
  required: ['MAX_USERS']

secretsSchema:
  type: object
  properties:
    ADMIN_PASSWORD:
      type: string
      format: password

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
    port:
      type: integer

plans:
  # The plan has no influence on the resource usage, so you should only define one.
  # You can also set plans to an empty array to disable the plan selection UI.
  - id: 0
    name: Default Plan
    description: Resource usage depends on the ci-profile of the landscape.
    parameters: {}

versions:
  0.0.1:
    ciProfile: debug
    # gitRef can be a commit-hash, branch or tag
    gitRef: 1a410efbd13591db07496601ebc7a059dd55cfe9
    description: Initial release
  1.0.0-rc:
    appVersion: Nextcloud v33
    ciProfile: prod
    gitRef: release-branches/1-0-0-rc
    description: |
      Release Candidate.
      Changelog:
        - Feature X
        - Feature Y
        - Fix Z
  1.0.0:
    appVersion: Nextcloud v33
    ciProfile: prod
    gitRef: release-tags/1-0-0
    description: Long Term Support Release

Provider Fields​

Below you can see where each schema type appears in the Codesphere UI:

Default landscape details​

For landscape-based providers, the following details are always computed and returned automatically:

For example, a landscape with a frontend service on port 3000 produces service_url_frontend_3000. To show these values on the service's details page, declare them in your detailsSchema:

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
      format: uri
    service_url_frontend_3000:
      type: string
      format: uri

Provider Versions​

Every provider must define at least one entry in versions. Each version pins the exact state of the landscape that gets deployed:

• gitRef: A commit hash, branch, or tag of the landscape repository.
• ciProfile: The CI profile from the landscape's ci.yml to use for deployment.
• appVersion (optional): A human-readable label for the deployed application version.
• description (optional): Markdown-formatted release notes shown to the user.

When creating a service, users choose which version to deploy. Users can change the version of their deployed services, triggering an upgrade or downgrade. For more information, see Upgrading to a new Version.

Publishing and Updating a Landscape-based Provider​

The recommended way to publish and update a provider is the idempotent upsert endpoint of the Codesphere Public API. Send a PUT request to /managed-services/providers:

• If no provider with the same name and schemaVersion exists yet, it is created.
• If one already exists, all mutable fields are updated in place.

This means you can use the same request to create a provider and to roll out later changes — you don't need to track whether the provider already exists. This is useful in CI/CD pipelines, for example.

You can either provide a Git URL that includes the provider.yml file or the full provider specification in the payload.

curl -X PUT "https://<your-codesphere-url>/api/managed-services/providers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/your-org/mattermost-landscape",
    "gitRef": "my-branch",
    "scope": {
      "type": "global"
    }
  }'

curl -X PUT "https://<your-codesphere-instance-url>/api/managed-services/providers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mattermost",
    "schemaVersion": "v1",
    "author": "Your Team",
    "displayName": "Mattermost",
    "iconUrl": "https://example.com/mattermost-icon.png",
    "category": "collaboration",
    "description": "Open-source team messaging platform.",
    "teamSingleton": true,
    "backend": {
      "landscape": {
        "gitUrl": "https://github.com/your-org/mattermost-landscape",
        "ciProfile": "production"
      }
    },
    "configSchema": {
      "type": "object",
      "properties": {
        "SITE_NAME": {
          "type": "string",
          "description": "Display name for your Mattermost instance"
        },
        "MAX_USERS": {
          "type": "integer",
          "description": "Maximum number of users allowed"
        }
      }
    },
    "secretsSchema": {
      "type": "object",
      "properties": {
        "ADMIN_PASSWORD": {
          "type": "string",
          "format": "password"
        }
      }
    },
    "detailsSchema": {
      "type": "object",
      "properties": {
        "hostname": { "type": "string" },
        "port": { "type": "integer" }
      }
    },
    "plans": [],
    "scope": {
      "type": "team",
      "teamIds": [42, 43]
    },
    "versions": {
      "0.0.1": {
          "ciProfile": "debug",
          "gitRef": "1a410efbd13591db07496601ebc7a059dd55cfe9",
          "description": "Initial release"
      },
          "1.0.0-rc": {
          "appVersion": "Mattermost v10",
          "ciProfile": "prod",
          "gitRef": "release-branches/1-0-0-rc",
          "description": "Release Candidate.\nChangelog:\n  - Feature X\n  - Feature Y\n  - Fix Z\n"
      },
          "1.0.0": {
          "appVersion": "Mattermost v10",
          "ciProfile": "prod",
          "gitRef": "release-tags/1-0-0",
          "description": "Long Term Support Release"
      }
    }
  }'

Provider Scopes​

When creating a provider, you can define its visibility scope:

Make the provider available to everyone in the instance:

"scope": {
  "type": "global"
}

Restrict the provider to specific teams:

"scope": {
  "type": "team",
  "teamIds": [1, 24, 56]
}

Team-singleton providers​

Set teamSingleton: true when a provider should expose at most one non-deleted managed service per team for a specific provider version. Codesphere rejects a second create request with an AlreadyExists error while an existing service for that team, provider, and version has not reached deleted status. This includes services that are still being deleted. Once the existing service reaches deleted, the team can create another one.

Leave teamSingleton unset or set it to false when teams may create multiple services from the same provider version.

Passing Configuration to Landscapes​

When a service is created from a landscape-based provider, the user's input is passed down to the landscape: properties from the configSchema are set as environment variables, and secrets from the secretsSchema are injected into the landscape's vault. Both can be referenced in the landscape's ci.yml:

schemaVersion: v0.2
run:
  my-service:
    steps:
      - command: ./start.sh
    env:
      APP_VERSION: ${{ workspace.env['APP_VERSION'] }}
      ADMIN_PASSWORD: ${{ vault.ADMIN_PASSWORD }}

In this example, APP_VERSION is a property of the provider's configSchema and ADMIN_PASSWORD is a property of the provider's secretsSchema.

Update Constraints with x-update-constraint​

The configSchema supports a custom extension x-update-constraint that lets you restrict how individual properties can be changed after a service has been created. This is useful for enforcing operational rules — for example, preventing storage from being decreased or locking down a database engine version after initial setup.

Add the x-update-constraint keyword to any property in your configSchema:

configSchema:
  type: object
  properties:
    storage:
        type: integer
        description: Storage allocation in GB
        x-update-constraint: increase-only
    version:
        type: string,
        description: Version of the Postgres DB.
        enum: ['17.6', '16.10', '15.14', '14.19', '13.22']
        x-update-constraint: immutable,

Available Constraints​

Supported Formats​

Provider schemas support the standard OpenAPI format values for validation:

int32, int64, float, double, byte, binary, date, date-time, password, uri, hostname

Beyond validation, some formats change how a value is rendered in the Codesphere UI:

For example, marking the detail URLs as format: uri turns them into links on the details page, and marking a secret as format: password masks it on entry:

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
      format: uri        # rendered as a link in the details section
      readOnly: true

secretsSchema:
  type: object
  properties:
    admin_password:
      type: string
      format: password   # rendered as a masked input in the create dialog

Dynamic Details with x-endpoint​

The detailsSchema supports a custom OpenAPI extension x-endpoint that allows you to fetch runtime details dynamically from your service. This is useful for retrieving live status information, metrics, or other data that changes after provisioning.

When x-endpoint is set on a property, Codesphere fetches the value from the specified endpoint at runtime and validates it against the property's schema.

Templating the endpoint URL​

The endpoint URL is a template: you can reference other detail fields with the ${{ .field_name }} syntax, and Codesphere substitutes their values before making the request. This lets you build the endpoint from details that are only known after provisioning — such as the default service_url_* fields.

detailsSchema:
  type: object
  properties:
    service_url_frontend_3000:
      type: string
      format: uri
      readOnly: true
    status:
      type: object
      properties:
        state:
          type: string
      # ${{ .service_url_frontend_3000 }} is replaced with that detail's value at runtime
      x-endpoint: '${{ .service_url_frontend_3000 }}/health'

In this example, the status property is fetched from the frontend service's /health endpoint. The template resolves ${{ .service_url_frontend_3000 }} to the running service's URL, so the final request goes to <service-url>/health, and the JSON response populates status.state.

Custom REST Backends​

Codesphere's Managed Services architecture is designed to be extensible. If landscape-based providers don't meet your specific requirements you can implement your own custom REST backend.