# Environment Rules

Environment rules map incoming repository events (pushes, pull requests) to Interlynk environments based on branch patterns. They control which environment an SBOM is assigned to when it arrives via a source control integration.

***

## How Environment Rules Work

When a webhook event arrives from GitHub, GitLab, or Bitbucket, Interlynk evaluates environment rules to determine the target environment:

```
Webhook Event → Match Event Type → Match Branch Pattern → Assign Target Environment
```

**Resolution order:**

1. **Project-level rules** are evaluated first (highest priority).
2. If no project-level rule matches, **organization-level rules** are evaluated.
3. If no rule matches, the SBOM is assigned to the `default` environment.

Within each level, rules are evaluated by **priority** (lower number = higher priority), then by **rule ID** as a tiebreaker.

***

## Default Rules (Auto-Created)

When you connect a source control integration (GitHub, GitLab, or Bitbucket) via OAuth, Interlynk automatically creates a set of organization-level environment rules. These defaults cover the most common branching workflows out of the box.

| Priority | Event Type           | Branch Pattern | Target Environment |
| -------- | -------------------- | -------------- | ------------------ |
| 1        | `PullRequestMerged`  | `main`         | `production`       |
| 2        | `PullRequestMerged`  | `develop`      | `development`      |
| 3        | `PullRequestMerged`  | `*`            | `default`          |
| 4        | `PullRequestCreated` | `main`         | `production`       |
| 5        | `PullRequestCreated` | `develop`      | `development`      |
| 6        | `PullRequestCreated` | `*`            | `default`          |
| 7        | `PullRequestUpdated` | `main`         | `production`       |
| 8        | `PullRequestUpdated` | `develop`      | `development`      |
| 9        | `PullRequestUpdated` | `*`            | `default`          |
| 10       | `RepositoryPush`     | `NA`           | `default`          |

**What this means in practice:**

* Merges, opens, or updates targeting `main` route SBOMs to **production**.
* Merges, opens, or updates targeting `develop` route SBOMs to **development**.
* All other PR activity falls through to **default**.
* Repository push events (without a PR context) go to **default**.

{% hint style="info" %}
These defaults assume a workflow where `main` is the production branch and `develop` is the development branch. If your team uses a different branching model (e.g., `master`, `trunk`, GitFlow with `release/*`), edit the auto-created rules or add project-level overrides to match your workflow.
{% endhint %}

***

## Matching Algorithm

When a webhook event arrives, Interlynk resolves the target environment using the following algorithm:

```
1. Collect applicable rules (project-level first, then organization-level)
2. Sort rules by priority (lower number = higher priority)
3. For each rule, check if the event type matches
4. If the event type matches, evaluate the branch pattern:
   a. Exact match   — pattern equals the branch name (e.g., "main" = "main")
   b. Glob match     — pattern contains a wildcard (e.g., "feature/*" matches "feature/login")
   c. Wildcard match — pattern is "*" (matches any branch)
5. Return the target environment of the first matching rule
6. If no rule matches, return "default"
```

**Key points:**

* For `RepositoryPush` events, the branch pattern is matched against `NA` rather than the branch name.
* Exact matches are evaluated before glob and wildcard patterns at the same priority level.
* The fallback to `default` ensures every event is routed to an environment, even if no rules are configured.

***

## Creating Environment Rules

### Organization-Level Rules

Organization rules apply across all products unless overridden by project-level rules.

1. Navigate to **Settings > Organization > Environment Rules**.
2. The rules table displays:

| Column                 | Description                              |
| ---------------------- | ---------------------------------------- |
| **Active**             | Whether the rule is enabled              |
| **Event Type**         | The webhook event that triggers the rule |
| **Target Branch**      | Branch pattern to match against          |
| **Target Environment** | The Interlynk environment to assign      |

### Supported Event Types

| Event Type           | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `RepositoryPush`     | Code pushed to a branch                                    |
| `PullRequestCreated` | A new pull request / merge request is opened               |
| `PullRequestMerged`  | A pull request / merge request is merged                   |
| `PullRequestUpdated` | A pull request / merge request is updated with new commits |

### Branch Pattern Matching

Branch patterns support the following syntax:

| Pattern       | Matches                                          | Example                              |
| ------------- | ------------------------------------------------ | ------------------------------------ |
| Exact         | Single specific branch                           | `main`, `master`, `develop`          |
| Glob wildcard | Branches matching a prefix/suffix                | `feature/*`, `release/*`, `hotfix/*` |
| Wildcard      | All branches                                     | `*`                                  |
| `NA`          | Events without a branch (e.g., some push events) | `NA`                                 |

### Target Environments

Target environments map to Interlynk environment names:

| Environment   | Typical Use                          |
| ------------- | ------------------------------------ |
| `development` | Feature branches, development builds |
| `production`  | Main/master branch, release tags     |
| `default`     | Catch-all for unmatched events       |

### Project-Level Rules

Project-level rules override organization rules for specific products. They are configured per project and do not have an explicit target environment — the project name is used as the environment identifier.

{% hint style="info" %}
Duplicate rules across sibling projects in the same product group are not allowed.
{% endhint %}

### Priority

Rules within the same level are evaluated by priority number. **Lower numbers are evaluated first.** If two rules could match the same event, the higher-priority (lower number) rule wins.

***

## Example Configuration

### Production Stricter Than Development

A common pattern: route `main` branch pushes to `production` and everything else to `development`.

| Priority | Event Type         | Branch Pattern | Target Environment |
| -------- | ------------------ | -------------- | ------------------ |
| 1        | RepositoryPush     | `main`         | production         |
| 2        | PullRequestMerged  | `main`         | production         |
| 3        | RepositoryPush     | `release/*`    | production         |
| 4        | PullRequestCreated | `*`            | development        |
| 5        | RepositoryPush     | `*`            | development        |

With this configuration:

* Pushes to `main` → production environment (strictest policies)
* Merges to `main` → production environment
* Pushes to `release/1.0` → production environment
* Pull requests from any branch → development environment
* Pushes to any other branch → development environment

### CI Enforcement Workflow

Combine environment rules with environment-specific policies to enforce different standards:

1. **Create environment rules** that route branches to the correct environment.
2. **Configure environment defaults** (see [Environment Defaults](https://docs.interlynk.io/administration/environment-defaults)) with appropriate scanning settings per environment.
3. **Create policies** with environment-specific conditions:
   * Development: Warn on critical vulnerabilities.
   * Production: Fail on critical and high vulnerabilities.
4. **Enable PR comments** in environment defaults so policy results are posted on pull requests.

```
Developer pushes to feature/xyz
  → Environment rule matches: RepositoryPush + feature/* → development
  → Development policies applied (warn-only)
  → SBOM processed with development settings

Developer merges PR to main
  → Environment rule matches: PullRequestMerged + main → production
  → Production policies applied (fail on critical/high)
  → Stricter scanning and compliance checks
```

***

## Common Misconfigurations

| Issue                              | Symptom                                                     | Fix                                                                  |
| ---------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| No rules configured                | All SBOMs go to `default` environment                       | Create rules mapping your primary branches to environments           |
| Wildcard rule has highest priority | All events match the wildcard, specific rules never trigger | Set the wildcard rule to the lowest priority (highest number)        |
| Duplicate rules across projects    | Validation error when saving                                | Each project in a product group must have unique rules               |
| `main` branch not matched          | Production SBOMs appear in default environment              | Add a rule for `main` (or `master`) → production                     |
| PR events not triggering           | Pull request SBOMs not processed                            | Add rules for `PullRequestCreated` and/or `PullRequestMerged` events |

***

## Recommended Best Practices

* **Always create explicit rules for `main`/`master`** mapped to `production` to ensure production SBOMs are correctly categorized.
* **Use glob patterns** (`feature/*`, `release/*`) rather than listing individual branches.
* **Set wildcard (`*`) rules at the lowest priority** as a catch-all for unmatched branches.
* **Match your branching strategy**: If your team uses GitFlow, create rules for `develop`, `release/*`, `hotfix/*`, and `main`.
* **Use project-level rules** when specific products need different branch-to-environment mapping than the organization default.
* **Test your rules** by pushing to a branch and verifying the SBOM appears in the expected environment.