Set up Git and CI/CD promotion
Set up Git and CI/CD promotion
Itential provides a reference GitHub repository with pipeline templates, a recommended directory structure, and example asset bundles. Fork or copy this repository, add your assets, and configure it to connect to your Platform environments.
This guide explains how the pipeline works. For setup steps and environment configuration, see the README in the template repository.
Understand how versioning works
Promotions are triggered by git tags. You don’t run a deployment manually. Push a tag and the pipeline handles the rest.
This design ensures production promotion is always a deliberate, traceable action tied to a specific validated version. If staging reveals a problem, don’t push the production tag.
The pipeline calculates the next semantic version from your commit messages using Conventional Commits (feat:, fix:, feat!: for breaking changes). Commits that don’t follow this format won’t break the pipeline, but they won’t increment the version correctly.
Understand the pipeline stages
The pipeline runs the same logical stages regardless of which CI/CD platform you use.
Stage 1: Create a release candidate tag
Triggered by merge to main. Calculates the next semantic version from commit messages and creates a release candidate tag (RC tag) automatically.
Stage 2: Deploy to staging
Triggered by the RC tag. Imports all assets found in the repository into the staging environment and reports deployment status. The pipeline discovers assets based on the repository’s folder structure. See Organize your asset repository for the conventions it expects.
The pipeline imports assets in the order defined by your repository structure, but it cannot automatically resolve cross-bundle dependencies. Make sure every asset a workflow references (transformations, templates, sub-workflows) is present in the same promotion. See Promote assets in the right order for the recommended sequence.
Stage 3: Deploy to production
Triggered by a manual production tag push. Imports assets into the production environment and reports deployment status. Assign clear ownership of the production tag push within your team. This is the point at which a validated version becomes live.
