# Template tags and versioning
<subtitle>Use tags to version your templates and manage environment-based deployments</subtitle>

Template versioning allows you to maintain multiple versions of the same template using tags. This supports workflows such as semantic versioning, environment-based deployment, and progressive releases.

## Tag format

Tags follow the format `name:tag`, where `name` is your template identifier and `tag` is the version tag.

```
my-template:v1.0.0 // within your team
my-template:production // within your team
acme/my-template:v1.0.0 // Complete namespace reference
```

##Default tag

UCloud Sandbox automatically uses the `default` tag when you build or reference a template without specifying a tag. This means:

- `my-template` is equivalent to `my-template:default`
- Existing templates without tags continue to work seamlessly

```python
# These are equivalent
sandbox1 = Sandbox.create('my-template')
sandbox2 = Sandbox.create('my-template:default')
```

## Reference a specific build

Instead of using named tags, you can launch the sandbox from a specific build by passing its `build_id` directly. This is useful when you need to pin the sandbox to an exact build artifact - for example, during debugging or when reproducing an issue from a known build.

The format follows the same colon syntax as the label: `<template>:<build_id>` or `<namespace>/<template>:<build_id>`.

You can find `build_id` from the return value of `Template.build()` or by listing the tag using `Template.get_tags()`.

```python
from ucloud_sandbox import Sandbox

# Start the sandbox from a specific build ID
sandbox = Sandbox.create('my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')

# Use namespace
sandbox2 = Sandbox.create('acme/my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')
```

## Build with tags

You can use one or more tag build templates to create versioned builds.

### Single tag

```python
from ucloud_sandbox import Template

# Build with specific version tags
Template.build(template, 'my-template:v1.0.0')
```

### Multiple tags

Build with multiple tags, assigning multiple version tags to the same build artifact.

```python
from ucloud_sandbox import Template

# Build with multiple tags pointing to the same artifact
Template.build(template, 'my-template', tags=['v1.2.0', 'latest'])
```

## Manage tags

You can manage tags on existing template builds without rebuilding.

### Assign tags

Assign new tags to existing builds. This is useful when promoting a tested version to production or marking a version as stable.

```python
from ucloud_sandbox import Template

# Assign a single label
Template.assign_tags('my-template:v1.2.0', 'production')

# Assign multiple tags at once
Template.assign_tags('my-template:v1.2.0', tags=['production', 'stable'])
```

### Delete tag

Remove the tag from the template. The underlying build artifacts are still accessible through other tags.

```python
from ucloud_sandbox import Template

# Delete tag
Template.remove_tags('my-template', 'staging')
```

> Deleting a tag does not delete the build artifact. Other tags pointing to the same build will continue to work.

### List tags

Retrieve all tags of a template. Each tag includes the tag name, associated build ID, and the time the tag was assigned.

```python
from ucloud_sandbox import Template

tags = Template.get_tags('my-template')
for tag in tags:
    print(f"Tag: {tag.tag}, Build: {tag.build_id}, Creation Time: {tag.created_at}")
```

## Use case

### Semantic Versioning

Use semantic version tags to track releases and enable rollbacks.

```python
# Release version
Template.build(template, 'api-server:v1.0.0')
Template.build(template, 'api-server:v1.1.0')
Template.build(template, 'api-server:v2.0.0')

# Create a sandbox from a specific version
sandbox = Sandbox.create('api-server:v1.1.0')
```

### Environment tag

Use environment tags for deployment pipelines.

```python
import os

# Build new version
Template.build(template, 'my-app:v1.5.0')

# Promote in environment
Template.assign_tags('my-app:v1.5.0', 'staging')

# After testing, promote to production environment
Template.assign_tags('my-app:v1.5.0', 'production')

# Use in application
env = os.environ.get('ENV', 'staging')
sandbox = Sandbox.create(f'my-app:{env}')
```

### Latest and stable tags

Maintain rolling labels that always point to a specific version.

```python
# Build with version and latest tag
Template.build(template, 'my-tool', tags=['v3.0.0', 'latest'])

# Mark tested versions as stable
Template.assign_tags('my-tool:v2.9.0', 'stable')

# You can choose your risk tolerance
latest_sandbox = Sandbox.create('my-tool:latest') # latest
stable_sandbox = Sandbox.create('my-tool:stable') # Tested
```