> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cysmiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Map repository refs to deployment boundaries for policy conditions and production-focused reporting.

## Overview

Environments map repository refs to deployment boundaries such as production, staging, release, or development. Cysmiq uses those mappings to add environment context to vulnerabilities, secrets, code findings, manifests, packages, and package versions.

Environment context is useful when policies need to treat production risk differently from non-production risk. For example, a custom policy can match findings where `environment.is_production` is `true`.

<Info>Availability depends on your Cysmiq plan.</Info>

When enabled, workspace owners can manage default environment mappings from **Settings > Environments**. Repository-level environment settings are available from a repository's **Environments** tab.

## Default Environments

Default environments define the workspace-wide set of deployment boundaries that repositories inherit.

Each default environment has:

| Field                  | Purpose                                                   |
| ---------------------- | --------------------------------------------------------- |
| **Name**               | Human-readable environment name                           |
| **Key**                | Stable value used by policy conditions                    |
| **Description**        | Optional context for users                                |
| **Mark as production** | Marks the environment as production for policy conditions |

The **Key** is the value exposed to policies as `environment.key`. The **Mark as production** setting is exposed as `environment.is_production`.

## Reference Rules

Reference rules map branches or tags to an environment.

| Field          | Values             | Purpose                                              |
| -------------- | ------------------ | ---------------------------------------------------- |
| **Ref type**   | Branch, Tag        | Selects whether the rule applies to branches or tags |
| **Match type** | Prefix, Exact      | Selects how Cysmiq compares the rule to the ref name |
| **Pattern**    | Ref name or prefix | The branch or tag pattern to match                   |
| **Priority**   | Number             | Higher priority rules are evaluated first            |
| **Default**    | On, Off            | Provides a fallback for the selected ref type        |

For **Prefix** rules, Cysmiq treats the pattern as a prefix. A pattern entered as `release/*` is stored and evaluated as the `release/` prefix. For **Exact** rules, the ref name must match the pattern exactly.

## Resolution Order

When Cysmiq resolves the environment for a ref, it uses this order:

1. A repository **Reference override** for that specific branch or tag.
2. Matching repository-specific reference rules, ordered by highest **Priority** and then newest rule.
3. Matching default reference rules, ordered by highest **Priority** and then newest rule.
4. Repository-specific **Default** rules for the ref type.
5. Workspace default **Default** rules for the ref type.

If no rule or override matches, the ref has no environment context.

## Repository Customization

Repositories inherit default environments until they are customized. In a repository's **Environments** tab, owners can:

* Change the effective **Name**, **Key**, **Description**, or **Mark as production** setting for that repository.
* Add repository-specific **Reference rules**.
* Add **Reference overrides** that pin a specific branch or tag to an environment.
* Use **Revert to defaults** to remove repository-specific customization.

Adding a repository-specific rule for an environment replaces that environment's default rules for the repository. **Reference overrides** are more specific than rules and always win for the selected ref.

## Policy Conditions

Environment mappings feed policy facts. Custom policies can use:

| Policy condition field      | What it matches                                           |
| --------------------------- | --------------------------------------------------------- |
| `environment.key`           | The effective environment key for the matched ref         |
| `environment.is_production` | Whether the effective environment is marked as production |
| `reference.ref`             | The branch or tag name                                    |
| `reference.ref_type`        | `branch` or `tag`                                         |

See [Policy condition fields](/reference/policy-condition-fields) for the full source-backed field reference.

## Related Docs

* [Custom policies](/policies/custom-policies)
* [Policy condition fields](/reference/policy-condition-fields)
* [Default branch filters](/views-automation/default-branch-filters)