> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Set up Git and CI/CD promotion

> Configure automated, versioned asset promotion using Itential's pipeline templates and git tags.

Itential provides a [reference GitHub repository](https://github.com/itential/asset-repository-template) 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.

| Tag pattern                            | Target environment | Trigger                                    |
| -------------------------------------- | ------------------ | ------------------------------------------ |
| `v*-rc.*` (for example, `v1.1.0-rc.1`) | Staging            | Automatic on merge to `main`               |
| `v*` (for example, `v1.1.0`)           | Production         | Manual tag push after staging is validated |

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](https://www.conventionalcommits.org/) (`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](./organize-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](./promote-assets-between-environments#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.