App configuration

Understand app configuration, defaults, secrets, updates and deployment outcomes.

The Apps API accepts a config object for container runtime, network and resource requirements. For image apps, provide config.image. For repository apps, provide source and omit the image; the build determines it.

Configuration groups

Field	Purpose
image, registryAuth	Image reference and optional private-registry credentials
ports	Container ports and exposure protocols
env	Environment variables and write-only secrets
command, entrypoint	Container CMD and ENTRYPOINT overrides
startupCommand	Command executed inside the container after startup
healthcheck	Check command and interval
restartPolicy	Restart behavior, failure tolerance and task completion
instances	Minimum and maximum container count
stateful	Pin an instance to its server and disk
hardware	GPU requirements, RAM, disk and shared memory
placement	Allowed regions, providers and source IPs
grids	Grid IDs and priorities
volumes	Named persistent mounts for grid apps

The Apps reference contains every nested field, type and supported enum. Runtime validation and capacity checks still apply after schema validation.

Organization and compute permissions

Apps belong to their project’s organization and inherit its visibility. Developers can create and operate apps they can edit; only admins or an app’s creator can delete or move it. Grid targeting requires permission to deploy to the grid. Developers must target an accessible grid when serverlessEnabled is off. Grid quotas count live placements against the app’s creator; policy management is in the portal.

Defaults and units

When omitted on creation, the current defaults are 1 GiB RAM, 1 GB disk, one to three instances, no GPU, any region and 64 MiB shared memory. Set instance bounds explicitly when a workload should use exactly one instance.

App hardware memory and storage fields use bytes. Dedicated-server provisioning uses storageSizeGb, while billing amounts use US cents. Do not interchange these units.

Secrets

{
  "env": [
    {"key": "MODEL_NAME", "value": "your-model"},
    {"key": "MODEL_TOKEN", "value": "<secret-value>", "secret": true}
  ]
}

Secret values are write-only and return null in reads. On update, null preserves a stored secret. Registry passwords are also write-only; reads expose the registry username separately.

Update semantics

Input	Update behavior
Omitted field	Keeps the stored setting
Lists such as env, ports, volumes	Replaces the entire list
hardware, placement	Merges supplied keys
instances	Requires both min and max
grids.priorities	Replaces the priorities map
healthcheck: null, startupCommand: null	Clears the setting
Existing secret with value: null	Preserves its stored value

Read configuration before editing arrays, and serialize concurrent writers. Changing compute sizing or build source can require compute:spend. Updating a running app may redeploy it.

Repository source

{
  "name": "service",
  "source": {
    "kind": "github",
    "installationId": 12345678,
    "repo": "your-org/your-repo",
    "branch": "main",
    "dockerfilePath": "Dockerfile",
    "contextDir": ".",
    "autoDeploy": true
  },
  "config": {
    "ports": [{"port": 3000, "protocol": "http80_load_balancer"}],
    "instances": {"min": 1, "max": 1}
  }
}

The identifiers above are placeholders. Discover the actual installation and repository with the GitHub API. An inline dockerfileContent can supply the Dockerfile. Updates to build source return the ID of the rebuild they trigger; poll the build and then app status.

Additional creation options

Copy environment variables from another app

On creation, use envFrom to copy variables and secret values on the server. The caller needs Developer access to the source app as well as permission to create in the destination project. This takes a copy once; future changes to the source app do not propagate.

{
  "name": "web-copy",
  "config": {"image": "nginx:stable", "instances": {"min": 1, "max": 1}},
  "envFrom": {
    "projectId": "507f1f77bcf86cd799439011",
    "appId": "507f1f77bcf86cd799439012",
    "overrides": [{"key": "APP_ENV", "value": "staging"}]
  }
}

Replace the example IDs with the app to copy. Omit config.env when using envFrom; use overrides instead. Overrides match by key. A null value preserves the copied value, and a copied secret remains secret. If the source has no available configuration, the API returns 409 app_config_unavailable.

Clone a public GitHub repository

For a new repository-backed app, choose exactly one of source.repo or source.clone:

{
  "name": "service-copy",
  "source": {
    "kind": "github",
    "installationId": 12345678,
    "clone": {
      "sourceRepo": "example-org/example-service",
      "targetRepoName": "my-service",
      "targetVisibility": "private"
    }
  },
  "config": {"instances": {"min": 1, "max": 1}}
}

Replace the installation and repository with real values. The source must be public. sourceRepo accepts owner/name or a GitHub URL, optionally with /tree/<branch>; sourceRef can select a branch, tag or commit. The destination is created in the connected account and defaults to private visibility. A member of the project’s organization with permission to edit it can make this request. Omit config.image and config.registryAuth; the build supplies the image.

Cloning runs in the build's vcs_import step. Follow the returned build ID, inspect errors or logs, and then poll app status. browse_github / the GitHub contents API can inspect source files; source.dockerfileContent supplies an inline Dockerfile if needed.

Placement and project moves

Check placement before creating an app with POST /projects/{projectId}/placement, or check stored configuration and proposed changes with POST /projects/{projectId}/apps/{appId}/placement. These are read operations despite using POST and require apps:read. They report current capacity, hibernated capacity, provisioning possibilities and sampled rejection reasons; they do not reserve capacity.

POST /projects/{projectId}/apps/{appId}/move takes targetProjectId and requires apps:admin. Both projects must belong to the same organization. The caller must be an admin or the app’s creator and be allowed to edit the destination project. Use the returned destination project ID for later requests.

Creation outcomes

start.state	Meaning	Next action
requested	Start accepted	Poll app status
deferred	Capacity is being acquired first	Inspect provisioning and poll status
building	Repository image is being built	Poll the returned build ID
failed	The app exists, but its automatic start failed	Read the error, correct the cause and start the existing app

An HTTP success is not a readiness signal. Use the status resource and its returned endpoints to decide when traffic can reach the app.