For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10

Deploy your project

Deploy your project to an environment assigned to your workspace, for example a testing, staging, or production environment.

Deployment environments​

You deploy a project to an environment, not to a cluster. The deploy dialog lists the environments that are assigned to the workspace of the project. Each entry shows the following details:

DetailDescription
NameThe name of the environment.
ClusterThe cluster that hosts the environment. Camunda Hub shows the cluster only if it's needed to tell environments apart.
VersionThe Camunda version of the cluster, for example Camunda 8.9.
TagsThe tags of the cluster, for example dev, test, stage, or prod.
StatusThe status of the environment.

An organization admin decides which environments a workspace can use. Camunda Hub doesn't offer any other targets, and it doesn't select the next environment for you when you promote a project. You choose the environment you want to deploy to.

Prerequisites​

Before you deploy a project:

Camunda Hub doesn't check your permissions before you deploy. The cluster decides whether you can deploy, and Camunda Hub shows you the result.

Deploy your project​

Once you've validated your process, deploy your project to an environment in your development lifecycle, such as testing, staging, or production. For example, deploy to your testing environment to run automated tests or make it available for testing.

  1. In your workspace, open a project.
  2. At the top right of the project view, click the Deploy & run combo button, and select Deploy latest changes. This opens the Deploy project dialog.
  3. Under Deployment environment, select the environment to deploy to. Camunda Hub preselects the first one.
  4. If the environment has Logical Tenants, select one under Logical tenant. In Self-Managed, you can enter a Logical tenant ID, which is optional.
  5. In Self-Managed, if the cluster uses Basic authentication, enter your Username and Password under Authentication.
  6. Click Deploy to deploy the project to the selected environment.

When you deploy from the project homepage, all BPMN, DMN, and form files in the project are deployed as a single bundle. Camunda Hub confirms a successful deployment with Project deployed!

note

If any resource fails to deploy, the whole deployment fails and the environment state remains unchanged. This safely ensures that a project cannot be deployed incompletely or in an inconsistent state.

tip

If you don't want to deploy all resources in a project, you can deploy an individual resource.

Logical Tenants​

If multi-tenancy is enabled, provide a Logical Tenant for the target environment. If the environment has more than one Logical Tenant, choose the one to deploy to. If it has exactly one, Camunda Hub selects it automatically. On SaaS, a cluster that doesn't support tenants doesn't need one.

Environment status​

The status of an environment decides whether you can deploy to it:

StatusWhat it means for deployment
HealthyYou can deploy.
UnhealthyYou can deploy, but the deployment may fail because the environment is unhealthy.
UpdatingYou can deploy, but the deployment may fail because the environment is updating.
PausedYou can't deploy until the environment is resumed. Resume the environment first.
ResumingYou can't deploy. Wait until the environment is healthy.
CreatingYou can't deploy. Wait until the environment is ready.
UnavailableYou can't deploy, for example because the environment is temporarily unavailable.
UnknownYou can deploy, but the deployment may fail because the status of the environment is unknown.

For how the status follows the state of the cluster, see environment statuses. To resume a paused environment, click Resume next to it. Only organization owners, admins, and DevOps users see this button. You can also resume the environment from the environments page.

No environment available​

If no environment is assigned to the workspace, the dialog shows No deployment environments available. An organization admin must assign an environment to the workspace. If you can manage the environments of the workspace, click Manage workspace environments in the dialog to open the workspace settings.

Production environments​

Camunda Hub treats an environment as a production environment if its tags include prod. Your organization can require that a project snapshot is approved before anyone deploys it to a production environment. When this is enabled, and you select a production environment, the dialog shows one of the following messages:

MessageMeaning
Approval requiredThe project snapshot must be approved by a reviewer before it can be deployed to a production environment.
Snapshot requiredDrafts can't be deployed to a production environment. Create a project snapshot, get it approved, and deploy it. Click Show snapshots to open the snapshots of the project.

Organization admins configure this in the project deployment settings. Learn how to request a review.

Run your project​

You can manually run your project to test it after it has been deployed to an environment.

note

Use Test mode to validate and debug your project against any environment assigned to your workspace. Use Run to execute a full process instance of your already-deployed project, for example to exercise your real job workers and APIs on a testing, staging, or production environment.

To run your project:

  1. In your workspace, open a project.
  2. At the top right of the project view, click Deploy & run to open the Deploy & run modal.
  3. Select the process for which you want to start a new instance in Process to run.
  4. Select Deploy & run to start a new instance.
    • Before the process instance starts, all resources are redeployed if required so the new instance uses their latest state.
    • After the process instance starts, you will receive an Instance started! notification. Click View process instance to open the process instance in the Operate of the environment, and monitor it.

You can also open the Deploy & run modal from the details page of any BPMN file in the project. In that case, the current process is run and the modal includes an additional option to select the resources to deploy.

If the target environment has authorizations enabled, make sure you have the following permissions to be able to view the process instance in Operate:

Resource typePermission
PROCESS_DEFINITIONREAD_PROCESS_DEFINITION and READ_PROCESS_INSTANCE
COMPONENToperate

Deployment errors​

If the deployment of a project fails (for example, because one or more of the contained resources has invalid implementation properties), a modal is shown containing the error message thrown by the Zeebe engine. If the cluster rejects the deployment because you lack the permissions to deploy to the environment, the message says so. Contact your organization admin to request them.

The message typically provides the name of the affected resource, the ID of the invalid diagram element, and the error details.

Deployment of external resources​

You can link BPMN processes, DMN decisions, or forms that are not part of the project itself (external resources) from any process inside a project. When you deploy the project, linked resources located outside the project are not deployed with the project, so you must deploy them separately.

Next steps​