Deployments

Deployment is delivering source code changes from Space to a deployment environment (a deployment target in terms of Automation). For example, you use Space to develop a web application. Your environment consists of a staging and a production server. These servers are your deployment targets. The process of delivering a new application version to a particular server is a deployment.

The main goal of deployments is to make the release lifecycle of your product more transparent:

With a predefined list of deployment targets (e.g., web, desktop, cloud, mobile, etc.), you always know where your product is deployed. A deployment schedule lets you plan how often the product is deployed.
A deployment lets you see which product version is now in production and for how long, which specific commit was used to deploy the production version, history of changes between the previous and the current version, and more.
(Not yet available) In the future, deployments will be able to perform a target health check: receive the current status of the deployment target and report incidents.

Note that deployments and deployment targets are just abstractions. You can use them to track anything: the latest version of a package published to a package repository, a desktop or a mobile application; a web application deployed to a Kubernetes cluster, cloud, or your local web server, and so on.

Deployments and CI/CD pipelines

Deployments are an addition to and continuation of your existing CI/CD pipelines. Deployments don't do any CI/CD tasks by themselves: They don't compile code or publish build artifacts to external servers. A deployment is only a state machine that tracks deployment status by receiving updates from a CI/CD tool. To send the status updates, the CI/CD tool can use either the space command-line tool or Space HTTP API. Practically, this means that deployments can work with any CI/CD tool be it Space Automation or an external CI/CD server like JetBrains TeamCity, Jenkins, GitHub Actions, etc.

The deployment workflows may vary depending on how the release process is organized in a company. For example, a workflow that includes all deployment states might look like this:

A developer pushes a commit to the release branch.
The CI/CD tool creates a deployment in Space. The deployment has the scheduled status.
The CI/CD tool starts the build process, and changes the deployment status to deploying.
Once the deployment is completed, the CI/CD tool changes the deployment status to current.
A former current version becomes completed.

To get started, you don't have to use all the states. It's possible to omit the states that are of no use for your case.

To get started with deployments

Prerequisites: You have an existing CI/CD pipeline that delivers changes from a release branch to a deployment environment.

Create a deployment target.
Get a Space authorization token. Your CI/CD tool needs this token to be able to change deployment status in Space.
In the existing CI/CD pipeline, add a build step that creates a deployment in the deploying state. After the build is finished, add a build step that changes the current deployment status.
Improve your workflow if required. For example:
- Use the CI/CD tool to schedule new deployments.
- If the deployment requires a lot of time, report not only the current but also the deploying status.
- Add reporting of other states.

Deployments and branches

The concept of deployments implies that there can be only one deployment for a Git branch. When creating or updating a deployment, you have to specify either a Git branch or a particular commit ID.

Deployment status

A deployment lifecycle includes the following stages:

scheduled	A new version is scheduled for deployment.
deploying	The deployment is in progress. You can set this status manually, or a CI/CD tool can set it once the build starts.
current	The CI/CD tool has deployed the new version to the deployment target. You can set this status manually, or a CI/CD tool can set it after the build completes.
hanging	The time spent in the deploying status exceeds the specified timeout (the default is 30 minutes). Space can set this status automatically (disabled by default).
failed	The CI/CD tool failed to deploy the new version. A CI/CD tool can set this status once the build fails or Space can set this status automatically (disabled by default) after the specified timeout (the default is 120 minutes).
completed	A successfull deployment of an older version gets this status automatically after a newer version becomes current.

You can track the deployment status in the deployment target timeline.

Create and edit a deployment target

To create a deployment target

Navigate to the project where you want to create a deployment target.
On the project sidebar, choose Deployments.
Click New target.
On the New target page, specify its Name, Description, and other settings:
- Key: a unique identifier that you will use to specify the target in HTTP requests or Automation jobs.
- Repositories: the Git repositories that contain the code you want to deploy.
Click Create.

To edit deployment target settings

Open the project's Deployments page, then open the deployment target.
On the Details page, edit basic target settings like Name and associated Repositories.
On the Scheduling page, specify the following settings:
- Show manual controls: Defines whether it is possible to change the deployment status manually on the deployment page.
- Set to hanging state automatically: If the deployment doesn't change its status in the amount of time specified in After X minutes, Space will change the deployment status to hanging.
- Set to failed state automatically: If the deployment doesn't change its status in the amount of time specified in After X minutes, Space will change the deployment status to failed.
Click Save.

Get a Space authorization token

To change a deployment status in Space, your CI/CD tool needs a Space authorization token. To get one, you must create a new application in Space and grant it permissions for working with deployments.

Note that if you're going to use deployments from Space Automation jobs, creating a Space authorization token is not required. Space Automation uses a special account that already has the required permissions.

On the main menu, click Extensions and choose Installed to organization.
Click New application.
Give your application a unique name and click Create, then Go to application settings.
Open the Authorization tab. Under In-context Authorization, click Authorize in project.
In the Authorize in Project window, specify your project and click Authorize.
Click Configure and in the list of permissions, enable the required permissions:
- View deployments: list deployments for a specific target.
- Modify deployments: change deployment status.
- Modify deployment targets: change deployment target settings. Typically, a CI/CD tool doesn't need this permission.
Click Save.
If you're a project administrator, the permission request will be approved automatically. Otherwise, you must wait until the administrator approves the request.
Return back to the application main settings page and open the Permanent Tokens tab.
Click New permanent token, specify a token name and its expiration date.
Click Create, copy a token value, and save it in a secure location. Next in this section, we will refer to this token as space_auth_token.

Schedule a deployment

Scheduling a deployment means creating a deployment in the scheduled state.

Deployments are associated with project Git branches. Therefore, when scheduling a deployment, you must specify a repository and a branch for a deployment. Optionally, you can specify a particular commit ID.

Depending on your workflow, you can create a new deployment manually, with the Space command-line tool, with Space Automation, or with the Space API.

To schedule a deployment

Get the Docker image with the Space command-line tool from https://public.registry.jetbrains.space/p/space/containers/space-cli:latest.
Connect the command-line tool to Space:
./space configure https://mycompany.jetbrains.space space_auth_token
Here https://mycompany.jetbrains.space is the URL of your Space instance and space_auth_token is the Space authorization token. You have to do this only once – The tool saves the provided settings locally in the ~/.space/client-config file.
Use the schedule command to schedule a deployment. Typically, this command must be run by a CI/CD tool as a part of the deployment build. For example:
./space deployments schedule MY-WEB-APPLICATION production-server --version $DEPLOYMENT_VERSION --commit $DEPLOYMENT_COMMIT --ext-label 'My CI/CD service' --ext-url https://mycicdservice.url
Here:
- MY-WEB-APPLICATION: a project identifier (assigned to a project when you create it in Space).
- production-server: the name of the deployment target.
- $DEPLOYMENT_VERSION and $DEPLOYMENT_COMMIT: a version and a commit you want to deploy to the target.
  To specify a particular commit, use the following format <repo>:<branch>:<commitID> where <repo> and <branch> are obligatory, and <commitID> is optional. For example, mywebapp:main:538dc16b. To use the latest commit, specify HEAD.
  If there's an existing deployment for this branch in the scheduled state, the ./space deployments schedule command will update this deployment. If there's no such deployment, a new deployment will be created.
- --ext-label, and --ext-url let you provide the name and the URL of the CI/CD tool that performs the deployment. For example, this could be a link to the corresponing CI/CD build, to the deployment target, or anything else. This link will be shown in Space next to the deployment.
For more information about space commands, run
./space deployments --help

To schedule a deployment

Use the Space SDK client in your Automation job. For example:
job("Deploy") { container("Run deploy script", image = "gradle:7.1-jre11") { kotlinScript { api -> // ... api.space().projects.automation.deployments.schedule( // get id of the current project project = api.projectIdentifier(), // deployment target name targetIdentifier = TargetIdentifier.Key("production-server"), version = "1.0.0", externalLinkLabel = "My CI/CD service", externalLinkUrl = "https://mycicdservice.url" // commitRefs is not required // the deployment will get the ID of the current commit - // the one that contains the currently running .space.kts ) } } }

To schedule a deployment

Send a POST request to the deployments/schedule endpoint. For example:
POST https://mycompany.jetbrains.space/api/http/projects/id:project-id/automation/deployments/start Authorization: Bearer [[[space_auth_token|https://www.jetbrains.com/help/space/deployments.html#obtaining-a-space-access-token]]] Accept: application/json Content-Type: application/json { "targetIdentifier": "key:production-server", "version": "1.0.0", "commitRefs": [ { "repositoryName": "my-web-app", "branch": "release", "commit": "abc1234" } ] }

To schedule a deployment

Open the project's Deployments page, then open the deployment target.
Open the deployment target where you want to create a new deployment.
Click New, then choose Deployment.
On the New Deployment page:
- Specify a Version that will be deployed to the target.
- Under repository name, choose a branch and, optionally, a commit that you want to deploy. If there still could be changes in this branch, you can choose Latest instead of a particular commit.
- In Status, leave scheduled.
- In Scheduling, specify date and time of the deployment.
- Under Display options, you can provide a deployment description and specify an External link that you want to associate with the deployment. For example, this could be a link to the corresponing CI/CD build, to the deployment target, or anything else. This link will be shown in Space next to the deployment.
Click Create.

Start a deployment

Starting a deployment means changing the status of an existing deployment from scheduled to deploying. A deployment target can have only one deployment with the deploying status at a time. If such a deployment exists, your request to start a deployment will update the existing one.

After you send a request to start a deployment:

Space will look for an existing scheduled deployment that has the same Git branch in the settings.
If such a deployment is found, Space will change its status to deploying. Note that a particular commit ID must be specified either in the existing scheduled deployment or in your request.
If there's no scheduled deployment or a commit ID is not provided, your request will fail.

Depending on your workflow, you can start a deployment manually in Space, with the Space command-line tool, with Space Automation, or with the Space API.

To start a deployment

Get the Docker image with the Space command-line tool from https://public.registry.jetbrains.space/p/space/containers/space-cli:latest.
Connect the command-line tool to Space:
./space configure https://mycompany.jetbrains.space space_auth_token
Here https://mycompany.jetbrains.space is the URL of your Space instance and space_auth_token is the Space authorization token. You have to do this only once – The tool saves the provided settings locally in the ~/.space/client-config file.
Use the start command to change the deployment status to deploying. For example:
./space deployments start MY-WEB-APPLICATION production-server --version $DEPLOYMENT_VERSION --commit $DEPLOYMENT_COMMIT
Here:
- MY-WEB-APPLICATION: a project identifier (assigned to a project when you create it in Space).
- production-server: the name of the deployment target.
- $DEPLOYMENT_VERSION and $DEPLOYMENT_COMMIT: a version and a commit you want to deploy to the target.
  To specify a particular commit, use the following format <repo>:<branch>:<commitID>. For example, mywebapp:main:538dc16b.
  If the scheduled deployment has some other commit ID or version specified, your request will update them. For example, you scheduled a deployment of the version 1.0.0 based on the commit mywebapp:main:abc1234. If you run ./space deployments start ... 1.0.1 mywebapp:main:def5678, the deployment in Space will change the commit ID to def5678 and the version to 1.0.1.
For more information about space commands, run
./space deployments --help

To start a deployment

Use the Space SDK client in your Automation job. For example:
job("Deploy") { container("Run deploy script", image = "gradle:7.1-jre11") { kotlinScript { api -> // ... api.space().projects.automation.deployments.start( // get id of the current project project = api.projectIdentifier(), // deployment target name targetIdentifier = TargetIdentifier.Id("production-server"), version = "1.0.0", // With syncWithAutomationJob = true, // Space will automatically change deployment status // based on the job execution result. // If the job fails, the deployment fails as well. // If the job is successful, the deployment becomes 'current'. syncWithAutomationJob = true // commitRefs is not required // the deployment will get the ID of the current commit - // the one that contains the currently running .space.kts ) } } }

To start a deployment

Send a POST request to the deployments/start endpoint. For example:
POST https://mycompany.jetbrains.space/api/http/projects/id:project-id/automation/deployments/start Authorization: Bearer [[[space_auth_token|https://www.jetbrains.com/help/space/deployments.html#obtaining-a-space-access-token]]] Accept: application/json Content-Type: application/json { "targetIdentifier": "id:production-server", "version": "1.0.0", "commitRefs": [ { "repositoryName": "my-web-app", "branch": "release", "commit": "abc1234" } ] }

To start a deployment

Open the project's Deployments page, then open the deployment target.
Open the deployment target.
Find the scheduled deployment and choose the deploying status in the dropdown list.

Finish or fail a deployment

Finishing a deployment means changing the status of a deployment to current. Initially, the deployment must be either in the deploying or scheduled state. You can also create a new deployment with the current status. If, for some reason, the deployment script fails, you can fail the deployment as well, i.e. change its status to failed. A deployment target can have only one deployment with the current status at a time.

After you send a request to finish a deployment:

Space will look for an existing deploying deployment that has the same Git branch in the settings.
If such a deployment is found, Space will change its status to current.
If a deploying deployment is not found, Space will look for an existing scheduled deployment with the same Git branch and commit ID.
If such a scheduled deployment is found, Space will change its status to current.
Otherwise, Space will create a new deployment with the current status.
If there was an existing deployment with the current status, it will change its status to completed.

Depending on your workflow, you can finish a deployment manually in Space, with the Space command-line tool, with Space Automation, or with the Space API.

To finish a deployment

Get the Docker image with the Space command-line tool from https://public.registry.jetbrains.space/p/space/containers/space-cli:latest.
Connect the command-line tool to Space:
./space configure https://mycompany.jetbrains.space space_auth_token
Here https://mycompany.jetbrains.space is the URL of your Space instance and space_auth_token is the Space authorization token. You have to do this only once – The tool saves the provided settings locally in the ~/.space/client-config file.
Use the finish command to change the deployment status to deploying. For example:
./space deployments finish MY-WEB-APPLICATION production-server --version $DEPLOYMENT_VERSION --commit $DEPLOYMENT_COMMIT
Here:
- MY-WEB-APPLICATION: a project identifier (assigned to a project when you create it in Space).
- production-server: the name of the deployment target.
- $DEPLOYMENT_VERSION and $DEPLOYMENT_COMMIT: a version and a commit you want to deploy to the target.
  To specify a particular commit, use the following format <repo>:<branch>:<commitID>. For example, mywebapp:main:538dc16b.
To fail a deployment, use the fail command. For example:
./space deployments fail MY-WEB-APPLICATION production-server --version $DEPLOYMENT_VERSION --commit $DEPLOYMENT_COMMIT
For more information about space commands, run
./space deployments --help

To finish a deployment

Use the Space SDK client in your Automation job. For example:
job("Deploy") { container("Run deploy script", image = "gradle:7.1-jre11") { kotlinScript { api -> // ... api.space().projects.automation.deployments.finish( // get id of the current project project = api.projectIdentifier(), targetIdentifier = TargetIdentifier.Key("production-server"), version = "1.0.0" // commitRefs is not required // the deployment will get the ID of the current commit - // the one that contains the currently running .space.kts ) // to fail the deployment, use ...deployments.fail() } } }

To finish a deployment

Send a POST request to the deployments/finish or deployments/fail endpoints. For example:
POST https://mycompany.jetbrains.space/api/http/projects/id:project-id/automation/deployments/finish Authorization: Bearer [[[space_auth_token|https://www.jetbrains.com/help/space/deployments.html#obtaining-a-space-access-token]]] Accept: application/json Content-Type: application/json { "targetIdentifier": "key:production-server", "version": "1.0.0", "commitRefs": [ { "repositoryName": "my-web-app", "branch": "release" } ] }

To finish a deployment

Open the project's Deployments page, then open the deployment target.
Open the deployment target.
If the deployment already exists, find it and choose the current or failed status in the dropdown list.
If there's no existing deployment, create a new one with the current status.

Subscribe to deployment target notifications

A deployment target has a Timeline which is essentially a deployment log.

To subscribe to deployment target notifications, open the target, and on the Timeline tab, click the Subscribe button. You will receive notifications in your personal Spacebox channel. Note that by default, you will be notified only when a deployment gets the current status. You can subscribe to notifications about other states in your personal subscriptions.

View deployment details and change settings

Find and open the required deployment target. The deployments are shown in the list.
Find the required deployment and click the version number. This will open the deployment details page consisting of tabs:
- Overview: general deployment information.
- Timeline: a dedicated chat channel where you can view deployment state change and communicate with other project members.
- Commits: shows the list of new commits comparing to the previous successful deployment.
  In turn, commits in a Git repository also have information about whether they were used for a particular deployment. To get this info, find a commit and open its Deployments tab.
- Merges, and Issues show merge requests and project issues associated with this deployment.
  In turn, issues and merge requests have information about the associated deployment on their Deployments tab.
To change the deployment settings, click Settings.

Delete a deployment

Find and open the required deployment target.
Find the required deployment and click the version number. This will open the deployment details page.
Click Delete.

Examples and guides

Refer to the corresponding topics for the examples on how to configure deployments with:

Space Automation
JetBrains TeamCity

Space Automation

Space Automation provides additional support for deployments. When creating a deployment in a job, you can specify the syncWithAutomationJob = true parameter. In this case, Automation will synchronize the job and deployment status: If the job finishes successfully, the corresponding deployment will get the current status. If the job fails, the deployment will be failed as well.

For example, a Space Automation job that performs deployment in a Gradle project might look like follows:

job("Deploy") {
    // run on commit to a branch containing "release"
    startOn {
        gitPush {
            anyBranchMatching {
                +"*release*"
            }
        }
    }

    container("Run deploy script", image = "gradle:6.1.1-jre11") {
        kotlinScript { api ->
            // create and start deployment
            api.space().projects.automation.deployments.start(
                project = api.projectIdentifier(),
                targetIdentifier = TargetIdentifier.Id("production-server"),
                version = System.getenv("JB_SPACE_EXECUTION_NUMBER"),
                // sync the job and deployment states
                syncWithAutomationJob = true
            )

            // build and deploy
            try {
                api.gradle("build")
                api.gradle("deploy")
            } catch (ex: Exception) {
                println("Deployment failed")
            }
        }
    }
}

JetBrains TeamCity

To use Space deployments from TeamCity builds

Get a Space authorization token.
Configure custom build parameters for Space deployments. When creating the parameters, in Kind, select Environment variable (env.). The recommended parameters:
- SPACE_URL: the URL of your Space instance, e.g. https://mycompany.jetbrains.space.
- SPACE_TOKEN: a Space authorization token.
- SPACE_PROJECT_KEY: a project key value of your Space project (available on the main page of your Space project).
- SPACE_PROJECT_NAME: a display name of your Space project.
- SPACE_DEPLOYMENT_TARGET: a key value of the deployment target (available on the details page of your deployment target).
- SPACE_EXT_LABEL and SPACE_EXT_URL: (optional) for example, this might be a link to a corresponding TeamCity build.
In the build configuration, add build steps:
- A step that runs before the actual deployment steps. This step must create a deployment in the deploying state using the space command-line tool. You can use the following step configuration:
  - Runner type: Command Line.
  - Run: Custom script.
  - Custom script: provide a shell script that first authorizes in Space and then creates a deployment. For example:
    space configure %\env.SPACE_URL% %\env.SPACE_TOKEN% space deployments start %\env.SPACE_PROJECT_KEY% %\env.SPACE_DEPLOYMENT_TARGET% --version %\build.number% --commit %\env.SPACE_PROJECT_NAME%:%\teamcity.build.branch%:%\build.vcs.number% --ext-label '%\env.SPACE_EXT_LABEL%' --ext-url %\env.SPACE_EXT_URL%
  - Run step within Docker container: specify public.registry.jetbrains.space/p/space/containers/space-cli:latest to run the step in a Docker image with the preinstalled space tool.
  - Docker image platform: Linux.
- A step that runs after the actual deployment steps. This step must change the deployment status to current or failed using the space command-line tool. The step configuration is similar to the one above excepting the Custom script it must run:
  space configure %env.SPACE_URL% %env.SPACE_TOKEN% space deployments finish %env.SPACE_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET% --version %build.number%
  or
  space configure %env.SPACE_URL% %env.SPACE_TOKEN% space deployments fail %env.SPACE_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET%
- The resulting build configuration may look as follows:
  steps { script { name = "Space notification - start deployment" scriptContent = """ space configure %env.SPACE_URL% %env.SPACE_TOKEN% space deployments start %env.SPACE_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET% --version %build.number% --commit %env.SPACE_PROJECT_NAME%:%teamcity.build.branch%:%build.vcs.number% --ext-label '%env.SPACE_EXT_LABEL%' --ext-url %env.SPACE_EXT_URL% """ dockerImage = "%env.SPACE_CLI_DOCKER_IMAGE%" } script { // do deploy... } script { name = "Space notification - finish deployment" executionMode = BuildStep.ExecutionMode.ON_SUCCESS scriptContent = """ space configure %env.SPACE_URL% %env.SPACE_TOKEN% space deployments finish %env.SPACE_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET% """ dockerImage = "%env.SPACE_CLI_DOCKER_IMAGE%" } script { name = "Space notification - fail deployment" executionMode = BuildStep.ExecutionMode.ON_FAILURE scriptContent = """ space configure %env.SPACE_URL% %env.SPACE_TOKEN% space deployments fail %env.SPACE_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET% """ dockerImage = "%env.SPACE_CLI_DOCKER_IMAGE%" } }

Last modified: 15 December 2023