---
title: Versioning
url: /docs/esc/environments/versioning/
---
Each time a change is made to an environment, a new immutable revision is created. You can manage and track changes to your secrets and configuration over time with a clear history you can audit, compare, and roll back.  You can assign tags to revisions, such as `production`, `v1.2.1`, or `stable`, to help organize and identify them.

When [importing an environment](/docs/esc/environments/imports/), you can choose to pin it to a specific version using a tag or revision number. This prevents automatic updates from the source environment, making it easier to test and roll out changes gradually. You can also specify which version to use when running commands with `esc run`, allowing you to target different environments for different tasks.

## View and compare version history

You can see the history of revisions using `esc env version history` or in the Pulumi Cloud Console.

```bash
$ esc env version history myorg/test
revision 3 (tag: latest)
Author: <Name> <User-ID>
Date: 2024-04-18 12:42:18.02 -0700 PDT

revision 2
...
```

Compare revisions using `esc env diff`.

```bash
$ esc env diff myorg/test@3 myorg/test@2
 Value

    --- myorg/test@3
    +++ myorg/test@2
...
```

## Tagging versions

You can tag your revisions with meaningful names like `prod`, or `stable`. Each environment has a built-in `latest` tag that always points to the environment’s most recent revision. Use `esc env version tag` to tag a revision.

To tag revision 3 of the `test` environment as `prod` for example, you can use the following command:

```bash
$ esc env version tag myorg/test@prod @3
```

### Using tagged versions

Once you tag a revision, you can use the tag to [open](/docs/esc/environments/working-with-environments/#opening-an-environment) a specific environment version.

```bash
$ esc open myorg/test@prod
```

You can also pin to a tagged version when importing an environment. This ensures you are using a known, fixed version that is not affected by subsequent changes to the source environment.

To pin an import in an ESC environment definition, append `@tag` to the environment name in the `imports` list:

```yaml
# myorg/myapp/dev
imports:
  - test@prod
```

To pin an environment used by a Pulumi IaC stack, append `@tag` to the environment name in your stack configuration file:

```yaml
# Pulumi.dev.yaml
environment:
  - test@prod
```