# Stage-aware public build inputs

A library or desktop app may need a public service URL or verification key embedded before release. From CLI 1.0.67, declare that contract in `kanject-cli/build-inputs.json`; release preparation resolves the selected stage and verifies the packaged assembly metadata.

## Declare what the project must embed

```json
{
  "schemaVersion": 1,
  "projects": [{
    "projectPath": "src/Acme.Client/Acme.Client.csproj",
    "properties": {
      "AcmeServiceEndpoint": {
        "fromStageEnv": "SERVICE_ENDPOINT",
        "visibility": "public",
        "required": true,
        "format": "https-url"
      }
    },
    "verification": {
      "kind": "assembly-metadata",
      "assemblyName": "Acme.Client",
      "keys": { "AcmeServiceEndpoint": "AcmeServiceEndpoint" }
    }
  }]
}
```

Each property becomes an MSBuild property. The verification map connects an assembly metadata key to that property; every declared property needs exactly one mapping. Use project-specific names because global properties also reach project references. Conflicting values for one property, invalid paths, unsupported versions, and release-controlled properties such as `Version` are rejected.

The project must embed and read the value. Passing a build property alone does not change runtime configuration. For assembly metadata, add this to the project and read it from the application or library assembly:

```xml
<ItemGroup>
  <AssemblyMetadata Include="AcmeServiceEndpoint" Value="$(AcmeServiceEndpoint)"
                    Condition="'$(AcmeServiceEndpoint)' != ''" />
</ItemGroup>
```

## Select public stage values

An existing deployment stage can supply its `env` values. A library repository without AWS deployment infrastructure can use a build-only `kanject-cli/stages/prod.json`:

```json
{
  "schemaVersion": 1,
  "kind": "build",
  "env": { "SERVICE_ENDPOINT": "https://api.example.com/" }
}
```

Build-only stages are for package preparation; they do not authorize deployment. Distribution still uses its existing deployment stage and destinations. A project with a build-input contract requires an explicit `--env` selection.

Use plain public values, or AWS SSM `String` parameters with explicitly configured provider, region, profile, and parameter path. `secret:` references and SecureString parameters are rejected. Formats are `text` and `https-url`; the latter requires HTTPS without credentials, a query, or a fragment. Passwords, bearer tokens, and private signing keys do not belong in shipped build inputs.

## Build and check the actual package

```bash
kanject doctor --env prod
kanject packages release prepare --env prod --json

# Distribution uses an existing deployment stage with destination mappings
kanject aws distribute --env prod --distributable client --no-publish
```

Doctor checks the local contract, not remote input values or the finished artifact. Release preparation shares one resolved snapshot across its isolated builds. Verification reads managed metadata without loading candidate code. Invalid inputs fail `KANCLI661`; missing or mismatched packaged metadata fails `KANCLI662`.

Configured package bundles use schema 2 and bind `evidence/build-inputs.json` into their inventory and digest. A trusted staging gate rechecks the expected stage and input digest; obtain those expectations from reviewed deployment configuration or approval, not unchecked candidate output.

```bash
kanject packages release stage artifacts/kanject-release --ci \
  --env prod --build-inputs-sha256 "$APPROVED_BUILD_INPUTS_SHA256"
```

> **Managed artifacts only:** Verification supports managed DLLs, NuGet packages, and ZIP payloads. Native AOT, single-file outputs without an inspectable assembly, and opaque installers require another independent verifier and are rejected. Use distinct package versions/identities or separate feeds for stage-specific bytes; one NuGet ID/version cannot hold different payloads.

Related: [Publish .NET packages](https://www.kanject.com/docs/packages/) · [Distribute desktop applications](https://www.kanject.com/docs/distribute/) · [Diagnostic codes](https://www.kanject.com/docs/cli-diagnostics/).

---
_Source: https://www.kanject.com/docs/cli-build-inputs/ · Kanject Docs_