Feature: Environment-Specific Secrets in Parent Stacks

[simple-container-forge]

Feature Design Request

Parent Issue: #60
Base Branch: simple-forge/issue-60-feature-request-environment-sp-ta3m0i

Problem

Currently, secrets defined in parent stack secrets.yaml files are globally available to all environments, creating security risks where production secrets (API keys, passwords) are accessible in dev/staging environments. There is also lack of isolation and naming conflicts when the same secret name needs different values per environment.

Scope

IN SCOPE: Add 'secretsConfig' section to server.yaml schema with inheritAll flag and per-environment configuration. Implement secret resolution logic supporting include mode (explicit allow list), exclude mode (block specific secrets), and override mode. Support three patterns: direct references (~), mapped references (${secret:KEY}), and literal values. Add validation for secret availability and configuration errors. Update JSON schema. OUT OF SCOPE: Changes to client.yaml schema, secret rotation, versioning, dynamic generation, UI/CLI changes beyond validation messages.

Acceptance Criteria

• AC-1: Basic Environment Isolation - When deploying to staging, only staging-configured secrets are available and production secrets are not accessible
• AC-2: Secret Mapping - When a client references DATABASE_PASSWORD in staging, the value resolves to DATABASE_PASSWORD_STAGING from secrets.yaml
• AC-3: Literal Values - When a parent stack has literal secret values configured, the literal value is used (not fetched from secrets.yaml)
• AC-4: Exclusion Mode - When using inheritAll: true with exclusions, all secrets except excluded ones are available
• AC-5: Backwards Compatibility - Existing parent stacks without the secretsConfig section work without modification and all secrets behave as before
• AC-6: Validation Errors - When a client references an unavailable secret, sc validate returns a validation error

Documentation

• docs/product-manager/environment-specific-secrets/requirements.md
• docs/product-manager/environment-specific-secrets/technical-specification.md
• docs/product-manager/environment-specific-secrets/examples.md
• docs/product-manager/environment-specific-secrets/validation-and-migration.md
• docs/product-manager/environment-specific-secrets/index.md

Notes

Documentation includes complete functional/non-functional requirements, data structures, secret resolution algorithm, JSON schema updates, validation logic, configuration examples, real-world use cases, 4-phase migration strategy, rollback procedures, and troubleshooting guide. Key implementation files identified: pkg/api/server.go (ServerDescriptor), pkg/api/secrets.go (SecretsDescriptor), pkg/api/read.go (ReadServerConfigs), pkg/api/models.go (ReconcileForDeploy).

Dependencies

• Server descriptor schema (pkg/api/server.go)
• Secret resolution logic (pkg/api/secrets.go)
• Configuration validation (pkg/api/read.go)
• JSON schema generation (cmd/schema-gen/main.go)

Priority: high

---

This issue was automatically created by the Multi-Role Orchestration system.

[simple-container-forge]

✅ Workflow Completed Successfully!

Great news! The Simple Forge has successfully processed your request.

📋 Job Details:

• Job ID: 923c41ab-2a59-496c-aa2b-4cc543452cae
• Job URL: https://forge.simple-container.com/jobs/923c41ab-2a59-496c-aa2b-4cc543452cae
• Branch: simple-forge/issue-130-feature-environment-specific-s-ta3mh6
• Workflow: View Results
• Completed: 2026-02-07 17:26:36 UTC

📝 Execution Summary:
I've processed the issue and made the following changes:

Let me now look at the existing JSON schema structure and check for any product manager documentation that might exist:

Now I have a clear understanding of the codebase. Let me create the architecture design documents. First, let me create the directory structure and files:

Now let me verify all the files were created properly and read them back:

All design files have been created successfully. Let me verify by listing the directory contents:

All design files have been created successfully. Now I'll provide the handoff JSON for the Developer role:

=== FORGE_HANDOFF_JSON_START ===
{
"schemaVersion": 1,
"role": "architect",
"summary": "Architecture design complete for environment-specific secrets feature. Created comprehensive documentation including system architecture, JSON schema updates, and detailed 8-phase implementation plan.",
"implementationRequests": [
{
"title": "Implement Environment-Specific Secrets in Parent Stacks",
"description": "Implement the secretsConfig feature for server.yaml that enables environment-specific secret filtering. Add include/exclude/override modes, support three reference patterns (direct, mapped ${secret:KEY}, literal), integrate with stack reconciliation, add validation, regenerate JSON schema, and add tests.",
"scopeGroup": "environment-specific-secrets",
"workflowType": "sequential",
"technicalNotes": "Core implementation files: pkg/api/server.go (add EnvironmentSecretsConfig, SecretsConfigMap types), pkg/api/secrets.go (add SecretResolver), pkg/api/read.go (add DetectSecretsConfigType), pkg/api/models.go (modify ReconcileForDeploy), pkg/api/validation.go (new file). All changes must maintain backwards compatibility - secretsConfig field is optional.",
"filesOrAreas": [
"pkg/api/server.go",
"pkg/api/secrets.go",
"pkg/api/read.go",
"pkg/api/models.go",
"pkg/api/copy.go",
"pkg/api/validation.go",
"pkg/api/secrets_config.go",
"pkg/api/secrets_config_test.go",
"cmd/schema-gen/main.go"
],
"acceptanceCriteria": [
"AC-1: Basic Environment Isolation - When deploying to staging, only staging-configured secrets are available and production secrets are not accessible",
"AC-2: Secret Mapping - When a client references DATABASE_PASSWORD in staging, the value resolves to DATABASE_PASSWORD_STAGING from secrets.yaml using ${secret:} syntax",
"AC-3: Literal Values - When a parent stack has literal secret values configured, the literal value is used (not fetched from secrets.yaml)",
"AC-4: Exclusion Mode - When using inheritAll: true with exclusions, all secrets except excluded ones are available",
"AC-5: Backwards Compatibility - Existing parent stacks without the secretsConfig section work without modification and all secrets behave as before",
"AC-6: Validation Errors - When a client references an unavailable secret, sc validate returns a validation error with clear message"
],
"docs": {
"designDocsPaths": [
"docs/design/environment-specific-secrets/architecture.md",
"docs/design/environment-specific-secrets/json-schema.md",
"docs/design/environment-specific-secrets/implementation-plan.md",
"docs/design/environment-specific-secrets/README.md"
],
"notes": "Implementation should follow the 8-phase plan in implementation-plan.md. Start with Phase 1 (data structures), work through to Phase 8 (documentation). All phases include acceptance criteria. Estimated 29-39 hours total."
},
"priority": "high",
"dependencies": [
"Server descriptor schema (pkg/api/server.go)",
"Secret resolution logic (pkg/api/secrets.go)",
"Configuration validation (pkg/api/read.go)",
"JSON schema generation (cmd/schema-gen/main.go)"
]
}
]
}
=== FORGE_HANDOFF_JSON_END ===

Changes have been committed to branch simple-forge/issue-130-feature-environment-specific-s-ta3mh6.

🎉 Next Steps:

• Review the changes in the Pull Request #133
• Test the implementation
• Merge the pull request when ready

Feel free to ask for any modifications or improvements!

[simple-container-forge]

✅ Workflow Completed Successfully!

Great news! The Simple Forge has successfully processed your request.

📋 Job Details:

• Job ID: c071428a-6f02-4924-8d56-c6bb52094ff9
• Job URL: https://forge.simple-container.com/jobs/c071428a-6f02-4924-8d56-c6bb52094ff9
• Branch: architect/issue-130-environment-specific-secrets
• Workflow: View Results
• Completed: 2026-02-07 17:20:36 UTC

📝 Execution Summary:
I've processed the issue and made the following changes:

Now let me read the existing documentation for this feature:

Let me search for the product manager documentation:

Let me check what documentation exists:

Let me read the key source files to understand the current implementation:

Let me also look at the JSON schema structure to understand how schema is generated:

Now I'll create the architecture design documents. Let me first create the directory:

Now let me create the architecture design document:

Now let me create the JSON schema update design document:

Now let me create the implementation plan document:

Now let me create a summary README for the design directory:

Now let me verify all the design files were created properly:

All files are created. Now let me read the README to verify its contents:

I have completed the architecture design for the environment-specific secrets feature. Here is the summary of what was created:

Architecture Design Documents Created

Files Created in /home/runner/_work/api/api/docs/design/environment-specific-secrets/:

1. README.md - Overview and navigation for the design documents
2. architecture.md - Comprehensive system architecture including:

• Current state analysis of existing secrets implementation
• New data structures (EnvironmentSecretsConfig, SecretsConfigMap, SecretResolver)
• Component architecture with data flow diagrams
• Secret resolution algorithm (6-step process)
• Integration points with existing code
• Three operation modes (include, exclude, override)
• Security and performance considerations

3. json-schema.md - JSON schema changes including:

• Go struct modifications for pkg/api/server.go
• Generated schema structure
• Validation patterns for all three modes
• Backwards compatibility approach
• IDE integration instructions
• Schema testing procedures

4. implementation-plan.md - Detailed 8-phase implementation plan:

• Phase 1: Data Structures and Schema (2-3 hours)
• Phase 2: Configuration Reading and Detection (3-4 hours)
• Phase 3: Secret Resolution Logic (6-8 hours)
• Phase 4: Stack Reconciliation Integration (4-6 hours)
• Phase 5: Validation (4-5 hours)
• Phase 6: JSON Schema Regeneration (1 hour)
• Phase 7: Testing (6-8 hours)
• Phase 8: Documentation (3-4 hours)
• Total Effort: 29-39 hours

Key Design Decisions

1. Optional secretsConfig field - Ensures backwards compatibility
2. Three modes of operation - Include (allow list), Exclude (block list), Override (replace)
3. Three reference patterns - Direct (~), Mapped (${secret:KEY}), Literal values
4. Fail-fast validation - Errors caught at configuration read time
5. No external dependencies - Uses existing secrets.yaml infrastructure

=== FORGE_HANDOFF_JSON_START ===
{
"schemaVersion": 1,
"role": "architect",
"summary": "Architecture design complete for environment-specific secrets feature. Created comprehensive documentation including system architecture, JSON schema updates, and detailed 8-phase implementation plan.",
"implementationRequests": [
{
"title": "Implement Environment-Specific Secrets in Parent Stacks",
"description": "Implement the secretsConfig feature for server.yaml that enables environment-specific secret filtering. Add include/exclude/override modes, support three reference patterns (direct/~, mapped/${secret:KEY}, literal), integrate with stack reconciliation, add validation, regenerate JSON schema, and add tests.",
"scopeGroup": "environment-specific-secrets",
"workflowType": "sequential",
"technicalNotes": "Core implementation files: pkg/api/server.go (add EnvironmentSecretsConfig, SecretsConfigMap types), pkg/api/secrets.go (add SecretResolver), pkg/api/read.go (add DetectSecretsConfigType), pkg/api/models.go (modify ReconcileForDeploy), pkg/api/validation.go (new file). All changes must maintain backwards compatibility - secretsConfig field is optional.",
"filesOrAreas": [
"pkg/api/server.go",
"pkg/api/secrets.

[Content truncated - full details available in workflow logs]

🎉 Next Steps:

• Review the changes in the Pull Request #131
• Test the implementation
• Merge the pull request when ready

Feel free to ask for any modifications or improvements!