# 3.3.0

**Release Date:** March 27, 2026

---

## ✨ New Features

### Aspire

#### Pipeline Publishing from Aspire Orchestration 🚀

**PR:** [#503](https://github.com/saif-corp/forge/pull/503)

Aspire-hosted applications can now publish Azure DevOps pipeline configuration directly from the AppHost. The new `SaifPipelinePublishingContext` enables the Aspire orchestrator to generate fully-wired pipeline YAML files (API, Auth, Event Service, Frontend, Subscription) alongside Bicep/Terraform — eliminating the need to manually maintain pipeline configuration files separate from the service definition.

**What's New:**

- ✅ **Pipeline code generation** — `AddPipelines()` on any SAIF service resource generates `.azdo/` pipeline YAML and vars files
- ✅ **All service types supported** — API, Auth, Event Service, Frontend (Web), and Subscription pipeline variants
- ✅ **Bicep cleanup** — `BicepCleanup` removes stale Bicep-generated artefacts when switching to Terraform provisioning
- ✅ **Foundry example** — `foundry/dotnet/aspire-publish` demonstrates a complete multi-service application with pipeline publishing
- ✅ **Feature annotations** — New `FeatureAnnotations` and `FeatureExtensions` provide a structured way to declare optional features (e.g. database, messaging) per service

**Benefits:**

- 🚀 Pipeline configuration is co-located with service definitions — changes propagate automatically
- 🔧 Eliminates pipeline drift between service code and deployment configuration
- 📦 Works alongside existing Terraform and Bicep provisioning workflows

**Documentation:** [Aspire Pipeline Publishing Guide](../guides/development/aspire-publish.md)

**Example:**

```csharp
var api = builder.AddSaifApiService("my-api")
    .AddPipelines();

var sub = builder.AddSaifSubscriptionService("my-sub")
    .AddPipelines();
```

---

### Terraform

#### Subscription Key API Policy Type for `saif-api-service` 🔑

**PR:** [#533](https://github.com/saif-corp/forge/pull/533)

The `saif-api-service` Terraform module now supports a third `api_policy_type`: `subscription_key`. This enables APIM-native subscription-based authorization where callers must present a valid APIM subscription key instead of (or in addition to) OAuth tokens.

**What's New:**

- ✅ **New policy type** — `api_policy_type = "subscription_key"` enables APIM subscription-required enforcement
- ✅ **API-scoped subscription** — An APIM subscription is automatically created and scoped to the target API (requires `is_experience_api = true`)
- ✅ **Dedicated policy templates** — New `api_policies_subscription_key/` folder contains the APIM inbound/outbound policies tailored for subscription key auth
- ✅ **Endpoint-level override support** — Endpoint-level policies respect the `subscription_key` type consistently

**Supported `api_policy_type` Values:**

| Value | Auth Mechanism |
|---|---|
| `standard` | OAuth2 / Entra tokens |
| `filevine` | Filevine-specific OAuth2 |
| `subscription_key` | APIM subscription key |

**Documentation:** [Subscription Key Authentication Guide](../guides/security/configuration/subscription-key-auth.md)

**Example:**

```hcl
module "my_api" {
  source           = "..."
  api_policy_type  = "subscription_key"
  is_experience_api = true
}
```

---

### CLI

#### App Search and Token Validate Commands 🔍

**PR:** [#523](https://github.com/saif-corp/forge/pull/523)

Two new commands have been added to the SAIF CLI to improve developer productivity when working with the service catalog and authentication tokens.

**`saif app search`**

Search the SAIF service catalog for registered applications by name or pattern. Returns application details including client ID, environment, and metadata.

```bash
saif app search --name "my-api"
saif app search --pattern "billing*"
```

**`saif token validate`**

Validate an existing access token to inspect its claims, check expiry, and verify audience/scope without making an API call.

```bash
saif token validate --token <jwt>
saif token validate  # reads token from current session
```

**Benefits:**

- 🔍 Quickly look up application registrations without leaving the terminal
- 🔐 Diagnose authentication issues by inspecting token claims directly
- ⚡ Reduces context-switching between the CLI, Azure Portal, and browser dev tools

**Documentation:** [SAIF CLI Reference](../reference/tools/saifcli.md)

---

## 🐛 Bug Fixes

### Terraform

#### Fix: Environment Name Matching in Secret Processing 🔧

**PR:** [#550](https://github.com/saif-corp/forge/pull/550)

Corrected environment name matching logic in the `saif-api-service` secret processing pipeline. Environment names were not being compared in a case-insensitive manner, causing secrets to be skipped or duplicated when environment identifiers used mixed casing.

#### Fix: Endpoint-Level Policy Overrides Respect `api_policy_type` 🔧

**PR:** [#544](https://github.com/saif-corp/forge/pull/544)

Endpoint-level APIM policy overrides now correctly inherit and respect the `api_policy_type` setting configured at the API level. Previously, overridden endpoints could fall back to the wrong policy template, causing auth inconsistencies for specific operations.

#### Fix: Unified APIM On-Error Status Code via Shared Context Variables 🔧

**PR:** [#539](https://github.com/saif-corp/forge/pull/539)

The APIM on-error policy now reads the HTTP status code from a shared context variable (`context.Variables`) rather than each policy template setting its own value independently. This eliminates drift between policy variants and ensures consistent error responses across `standard`, `filevine`, and `subscription_key` policy types.

---

## 📚 Documentation

### New Documentation

#### Aspire Pipeline Publishing Guide 🚀

**File:** `docs/guides/development/aspire-publish.md`

Comprehensive new guide covering how to use the Aspire pipeline publishing feature. Includes setup instructions, configuration options, service type-specific examples, and Foundry reference application walkthroughs.

#### Subscription Key Authentication Guide 🔑

**File:** `docs/guides/security/configuration/subscription-key-auth.md`

New guide for configuring APIM subscription key authentication in the `saif-api-service` module. Covers when to use subscription key auth, Terraform configuration, and integration patterns.

### Updated Documentation

#### SAIF CLI Reference 🛠️

**File:** `docs/reference/tools/saifcli.md`

Updated CLI reference documentation with `saif app search` and `saif token validate` command descriptions, usage examples, and flag reference.

---

## 📦 Dependencies

### .NET Packages

Several .NET packages were updated via Dependabot:

| Package Group | PRs |
|---|---|
| Dependencies group (2 packages) | [#547](https://github.com/saif-corp/forge/pull/547) |
| Dependencies group (4 packages) | [#536](https://github.com/saif-corp/forge/pull/536) |

### TypeScript Packages

Multiple TypeScript package updates across all workspaces:

| Package | PRs |
|---|---|
| `yaml` | `2.8.2` → `2.8.3` ([#542](https://github.com/saif-corp/forge/pull/542)) |
| `handlebars` | `4.7.8` → `4.7.9` ([#545](https://github.com/saif-corp/forge/pull/545)) |
| `picomatch` | Updated ([#541](https://github.com/saif-corp/forge/pull/541)) |
| `brace-expansion` | `1.1.12` → `1.1.13` ([#549](https://github.com/saif-corp/forge/pull/549)) |
| npm_and_yarn group (multiple) | [#543](https://github.com/saif-corp/forge/pull/543), [#548](https://github.com/saif-corp/forge/pull/548), [#546](https://github.com/saif-corp/forge/pull/546) |
| Dependencies group (6 packages) | [#540](https://github.com/saif-corp/forge/pull/540) |
| Dependencies group (3 packages) | [#535](https://github.com/saif-corp/forge/pull/535) |

---

## 🔄 Breaking Changes

None in this release ✅

---

## 📋 Additional Notes

- Total commits: 17
- Files changed: 216
- Contributors: Emmitt Johnson, Jason Coria Corona Yue, Copilot

---

### Support

- 📧 Teams Support Channel: [Support](https://teams.microsoft.com/l/channel/19%3Acb611810fb0b42b080cfff5590bdd51c%40thread.tacv2/Support?groupId=514d2dac-2d62-48ce-bf99-0fa0ce39469c&tenantId=a86cb8ed-369b-4df5-ace5-43811f6e08cf)

---