Deploying Flows custom apps

You can deploy your Flows custom app to CDF interactively from your machine (browser sign-in, no OAuth secrets in the terminal) or automate deployment in CI/CD with client credentials. Uploaded apps use the published-custom-apps data set (see Data set requirement).

Data set requirement

Flows custom apps are deployed as CDF files. For security, apps must be uploaded to a CDF data set with external ID published-custom-apps. Without this restriction, anyone with file upload access could deploy apps visible to all users in the project, including malicious apps. The data set requirement lets administrators control who can deploy Flows apps by scoping write access to this data set. The deploy tool resolves the published-custom-apps data set before upload. If it does not exist, the tool tries to create it. If both lookup and creation fail (for example, because of missing permissions), deployment fails with an error. Administrators should create the published-custom-apps data set in the CDF project and grant write access to users or service accounts that deploy apps.

Interactive deployment

The simplest path uses your browser for sign-in—no OAuth configuration in the terminal:

npx @cognite/cli@latest apps deploy --interactive

This will:

Build your app.
Open a browser window for you to sign in to CDF.
Prompt you to select a deployment target from app.json.
Package and deploy to your configured project.
Show a link to your deployed app.

Options

# Use the first deployment target (skip selection prompt)
npx @cognite/cli@latest apps deploy --interactive -d 0

# Use a specific project by name
npx @cognite/cli@latest apps deploy --interactive -d your-project-name

# Skip the build step (if already built)
npx @cognite/cli@latest apps deploy --interactive --skip-build

Draft and published versions

apps deploy uploads your app as a Draft version. To publish and activate it, see App lifecycle.

--published flag is used for legacy apps:

Scenario	Behavior
Legacy app, `--published` flag	Honored — deploys as published
App Hosting app, `--published` flag	Warning printed, flag ignored — always deploys as DRAFT. Use `apps publish .` / `apps activate .` instead

For App Hosting apps, use npx @cognite/cli@latest apps publish . and npx @cognite/cli@latest apps activate . to control visibility.

App Hosting lifecycle commands

For apps using App Hosting infrastructure ("infra": "appsApi" in app.json), use the following commands to manage the version lifecycle after deployment. Each version progresses through the states: DRAFT → PUBLISHED → ACTIVE.

Check status

Print the current deployment status of your app version:

npx @cognite/cli@latest apps status .

Publish a version

Transition the current version from DRAFT to PUBLISHED (visible but not yet the active version):

npx @cognite/cli@latest apps publish .

This command is idempotent — re-running on an already PUBLISHED or ACTIVE version is a no-op.

Activate a version

Set the current version as ACTIVE (the version users see). Publish the version if it’s still DRAFT:

npx @cognite/cli@latest apps activate .

If a previous version was active, the output reports which version it replaced.

Use --interactive to authenticate via browser sign-in when running these commands from your machine:

npx @cognite/cli@latest apps status . --interactive
npx @cognite/cli@latest apps publish . --interactive
npx @cognite/cli@latest apps activate . --interactive

Automated deployment (CI/CD)

For CI/CD pipelines, configure client credentials.

Prerequisites

OAuth client — A client ID registered in your CDF project.
Client secret — The secret for that client.
Permissions — The apphosting:read and apphosting:write capabilities assigned to the client (apphosting:run is for end users running apps, not needed for deployment). See Flows access control.

Ask your Cognite administrator to register an OAuth client with the required permissions.

Step 1: Configure app.json

Add deployClientId and deploySecretName to your deployment configuration:

{
  "name": "My App",
  "description": "My awesome Flows app",
  "externalId": "my-app",
  "versionTag": "1.0.0",
  "deployments": [
    {
      "org": "my-org",
      "project": "my-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "your-client-id",
      "deploySecretName": "MY_APP_SECRET"
    }
  ]
}

Field	Description
`name`	Display name in CDF
`externalId`	Unique identifier (kebab-case)
`versionTag`	Semantic version
`deployClientId`	OAuth client ID
`deploySecretName`	Environment variable name for the secret
`idpType`	Identity provider (`cdf` or `entra_id`). Defaults to `cdf`
`tenantId`	Microsoft Entra tenant ID (required when `idpType` is `entra_id`)
`published`	Legacy field: whether the app is visible to end users. Prefer `apps publish` / `apps activate` for App Hosting apps.

Microsoft Entra ID deployment

Set idpType to entra_id and provide tenantId:

{
  "deployments": [
    {
      "org": "my-org",
      "project": "my-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "your-entra-client-id",
      "deploySecretName": "MY_APP_SECRET",
      "idpType": "entra_id",
      "tenantId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

When idpType is entra_id, Flows requests a token from Microsoft Entra ID and derives the CDF scope from baseUrl (for example, https://greenfield.cognitedata.com/.default).

Step 2: Set the secret

Export the client secret:

export MY_APP_SECRET="your-client-secret"

In CI/CD, store secrets in your platform’s secret manager (for example, GitHub Actions repository secrets, Azure DevOps variable groups, or GitLab CI variables).

Step 3: Deploy

npm run deploy

This will:

Build your app (tsc && vite build).
Package dist/ into a zip.
Authenticate with client credentials.
Upload through the CDF Files API.
Make the app available in CDF.

Preview deployments

For pull request previews:

npm run deploy-preview

Multiple environments

Add multiple entries to deployments:

{
  "deployments": [
    {
      "org": "your-org",
      "project": "dev-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "dev-client-id",
      "deploySecretName": "DEV_SECRET"
    },
    {
      "org": "your-org",
      "project": "prod-project",
      "baseUrl": "https://api.cognitedata.com",
      "deployClientId": "prod-client-id",
      "deploySecretName": "PROD_SECRET"
    }
  ]
}

Versioning

Update versionTag in app.json for each release:

{
  "versionTag": "1.2.0"
}

Each version is stored in CDF so you can roll back if needed.

Troubleshooting

What permissions do I need to deploy?

Your OAuth client (for CI/CD) or user account (for interactive deployment) needs apphosting:read and apphosting:write. apphosting:run is for end users running apps and is not required for deployment. See Flows access control.

”Deployment secret not found”

Ensure the environment variable name matches deploySecretName:

export MY_APP_SECRET="your-secret"

“Failed to authenticate”

Check that:

The client ID is correct.
The client secret is valid and not expired.
The client has the required CDF permissions (including Files API write access).

Build fails

Run the build locally:

npm run build

Confirm you have access to the CDF project.
Ensure pop-ups are not blocked.
Try npx @cognite/cli@latest apps deploy --interactive --org your-org as a hint.

Build

Documentation Index

​Data set requirement

​Interactive deployment

​Options

​Draft and published versions

​App Hosting lifecycle commands

​Check status

​Publish a version

​Activate a version

​Automated deployment (CI/CD)

​Prerequisites

​Step 1: Configure app.json

​Microsoft Entra ID deployment

​Step 2: Set the secret

​Step 3: Deploy

​Preview deployments

​Multiple environments

​Versioning

​Troubleshooting

​What permissions do I need to deploy?

​”Deployment secret not found”

​“Failed to authenticate”

​Build fails

​Interactive sign-in issues

​Further reading