Introducing Deployments in Space
Today, we’ve reached an important milestone in Space Automation development. We’re releasing support for deployments, another piece of the puzzle in making Space a truly all-in-one solution.
A deployment is a Space entity that represents the delivery of source code changes to a deployment environment (a deployment target). For example, delivering a web app to a production server, publishing a mobile app on a store, uploading a distribution to an FTP server, and so on.
Read this blog post to learn how deployments can be helpful to you and how to get started with them.
Why you may need deployments
Deployments are helpful on many levels:
- As a user: Deployments let you track your code changes and answer questions like “Which product version is now in production?”, “Which specific commit was used to deploy the production version?”, “How many changes (commits) were there between version A and version B?”, etc.
- As a team: Deployments make the product release lifecycle more transparent. As you have a predefined list of deployment targets (such as web, desktop, cloud, mobile, and so on), you always know where your product is deployed. A deployment schedule lets you plan how often it is deployed. A target health check (not yet available) will soon show how things are going on a particular target.
- As a company: Deployments can also deliver company-wide benefits. For example, think of Space deployments as a uniform standard for defining deployment targets in your company. So every released product, application version, or internal service update is recorded and tracked. This could simplify managing risks in log4j-like scenarios. Having all targets defined in Space, you can easily track which library versions are delivered to the end users.
How deployments work
A deployment in Space doesn’t run any build scripts by itself. It is just a state machine that tracks the current deployment status. The status updates are sent by a CI/CD server with the help of the space command-line tool (provided as a Docker image: public.registry.jetbrains.space/p/space/containers/space-cli:latest) or with the Space HTTP API. There’s also an option to manually change the deployment state in the UI. This means that you can use deployments with any CI/CD tool of your choice, including Space Automation, JetBrains TeamCity, GitHub Actions, and others.
For example, this is what a deployment that includes all possible states looks like.
All states on this scheme except completed are optional: You can create a new deployment in any state.
How to get started with deployments
Suppose you have an existing CI/CD pipeline that delivers your product to some environment (target). In the simplest case, you can start with tracking when your deployment starts (the deploying state) and when it ends (the current state):
- You create a deployment target in Space.
- You get a Space authorization token. You will need it to authorize your CI/CD tool in Space.
- A trigger (creating a release branch, git push, schedule, etc.) runs the deployment script on your CI/CD (such as Space Automation, TeamCity, or another tool). This is where you should report the deployment state to Space:
- (Optional) Before the CI/CD server runs the script, it creates a deployment in the deploying state, e.g., with the space command-line tool:
space deployments start $PROJECT_KEY $TARGET_KEY --version $VERSION --commit $COMMIT_ID. Although this step is optional, it’s quite useful because it adds more transparency to the process. Users are notified that deployment is in progress. - After the deployment is finished, the CI/CD server must change its state to current, e.g., with the space command-line tool:
space deployments finish $PROJECT_KEY $TARGET_KEY --version $VERSION
If you skipped the previous step, the command will create a new current deployment. Otherwise, it’ll update the existing one. Learn more on how to finish a deployment.
This is what it might look like in a Space Automation job:
- (Optional) Before the CI/CD server runs the script, it creates a deployment in the deploying state, e.g., with the space command-line tool:
job("Deploy") {
// you can store the auth token as a secret
env["TOKEN"] = Secrets("space-auth-token")
container("Deploy to prod", "registry.jetbrains.team/p/myprj/docker/custom-image-with-space-cli") {
shellScript {
// staging-server is the target key
// JB_SPACE_EXECUTION_NUMBER serves as a version number
content = """
space configure ${'$'}JB_SPACE_API_URL ${'$'}TOKEN
space deployments start ${'$'}JB_SPACE_PROJECT_KEY staging-server --version ${'$'}JB_SPACE_EXECUTION_NUMBER --commit my-web-app:release:${'$'}JB_SPACE_GIT_REVISION
./do-deploy.sh
space deployments finish ${'$'}JB_SPACE_PROJECT_KEY staging-server
"""
}
}
}
- If the deployment fails, you can change its state to failed with
space deployments fail $PROJECT_KEY $TARGET_KEY --version $VERSION. We provide additional support for deployments in Space Automation. You can work with deployments directly by using the Space SDK in jobs. In addition, Space Automation can handle deployment status automatically. All you need to do is start a new deployment with thesyncWithAutomationJobparameter. It will synchronize the deployment status with the job run result:
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
)
// do deployment staff
// ...
}
}
}
After the script is successfully finished, the deployment becomes current, meaning that this is the actual application version deployed to the target environment.
- Once you deploy a newer version, the most recent current version will automatically become completed.
Basically, that’s enough to get started. Over time, you can improve your workflow, for example, by adding deployment scheduling somewhere before all other steps.
Get started with deployments and TeamCity
A TeamCity workflow looks very similar to the one above. Typically, for deployments, you use a Deployment build configuration. In this configuration, add two build steps as follows:
- Add one before the actual deployment steps. It must create a deployment in the deploying state.
- Add the other one after the deployment steps. It must change the deployment state to current.
The build configuration might look like this:
steps {
script {
name = "Space notification - start deployment"
scriptContent = """
space configure %env.SPACE_DEPLOYMENT_API_URL% %env.SPACE_NOTIFICATION_PERM_TOKEN%
space deployments start %env.SPACE_DEPLOYMENT_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET_ID% --version %build.number% --commit my-web-app:%teamcity.build.branch%:%build.vcs.number% --ext-service '%env.SPACE_DEPLOYMENT_EXT_SERVICE%' --ext-label '%env.SPACE_DEPLOYMENT_EXT_LABEL%' --ext-url %env.SPACE_DEPLOYMENT_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_DEPLOYMENT_API_URL% %env.SPACE_NOTIFICATION_PERM_TOKEN%
space deployments finish %env.SPACE_DEPLOYMENT_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET_ID%
"""
dockerImage = "%env.SPACE_CLI_DOCKER_IMAGE%"
}
script {
name = "Space notification - fail deployment"
executionMode = BuildStep.ExecutionMode.ON_FAILURE
scriptContent = """
space configure %env.SPACE_DEPLOYMENT_API_URL% %env.SPACE_NOTIFICATION_PERM_TOKEN%
space deployments fail %env.SPACE_DEPLOYMENT_PROJECT_KEY% %env.SPACE_DEPLOYMENT_TARGET_ID%
"""
dockerImage = "%env.SPACE_CLI_DOCKER_IMAGE%"
}
}
Integration with Space
Deployment target timeline
The way in which deployments are integrated with other Space subsystems is another important factor. First of all, each deployment target and deployment has its own timeline where it posts the deployment state changes. You can also subscribe to deployment events and receive notifications in your personal Spacebox channel.
Deployment timeline
Deployments also have a timeline. Moreover, a deployment timeline is more than just a log – it’s also a dedicated chat channel where you can communicate with other people involved in CD as part of a team or company.
Integration with VCS and Issues
Commits now have the Deployments tab that lets you see whether the commit was deployed. Merge requests and issues also have a similar Deployments tab.
What’s next
- Space Automation pipelines: The next major step after deployments. A deployment only tracks predefined states, whereas a pipeline may include an arbitrary number of custom stages. Pipelines will bring more control to the process: conditions for moving to the next stage as well as the ability to roll back a deployment or trigger a new one from Space. You’ll have the option to run a pipeline with Space Automation or just define a pipeline in Space and run all the steps using an external CI/CD tool.
- Deployment target health check: You’ll have the option to track the actual deployment state. Space will periodically check the health status of a deployment target and report any incidents.
Give it a try
If you’re involved in the product deployment process, try the deployments in action and give us your feedback! If you just want to figure out whether the deployment feature works for you and your team, you can start by creating and changing the deployment state manually in the Space UI.
Subscribe to Space Blog updates
