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.

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. If a signature is already present, the draft deploys with that signature. You can also add the signature separately. From your machine, see Signing Flows custom apps from the CLI. From a pipeline, see Signing Flows custom apps from CI/CD. To publish and activate the version, see How a version reaches Custom apps.

--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.

Publishing requires a developer signature, including on projects with Dev status. Production projects without Dev status need both that signature and Cognite’s app certification signature (.cert.sig) from application certification. Sign from your machine with Signing Flows custom apps from the CLI, or from a pipeline with Signing Flows custom apps from CI/CD.

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.
Capabilities — The apphosting:read and apphosting:write capabilities granted to the client via a group. These capabilities can be scoped to the app’s externalId from app.json. Add apphosting:run if the same client also needs to run the app. See Assign capabilities.

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.

npm run deploy uploads a draft. If a signature is already present, the draft includes it. You can also add the signature later. See Signing Flows custom apps from CI/CD.

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"
}

Roll back to a published version

Each version is stored in CDF. To point Custom apps at an earlier published, Cognite-certified version, set versionTag in app.json to that version, then run:

npx @cognite/cli@latest apps activate .

Do not run apps deploy against that versionTag. Published versions cannot be overwritten.

See New versions and rollback for when to roll back versus recertify.

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. You can scope these capabilities to the app’s externalId from app.json. Add apphosting:run if the same principal also needs to run the app. See Assign capabilities.

”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.

​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

​Roll back to a published version

​Troubleshooting

​What permissions do I need to deploy?

​”Deployment secret not found”

​“Failed to authenticate”

​Build fails

​Interactive sign-in issues

​Further reading

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

Roll back to a published version

Troubleshooting

What permissions do I need to deploy?

”Deployment secret not found”

“Failed to authenticate”

Build fails

Interactive sign-in issues

Further reading