Managing requirements that differ per environment configuration

ALM Atlassian Jira Software
, , , , , , , ,
1

Some of our requirements vary slightly between on-premises and cloud deployment environments, and we’re creating duplicate requirement issues which is causing traceability confusion. For example, authentication requirements differ (LDAP vs SSO), but the core business logic is identical.

We’re on Jira 9 and trying to decide between three approaches:

  1. Separate requirement issues per environment (current approach - causing duplicates)
  2. Single requirement with environment-specific child issues
  3. Single canonical requirement with custom fields indicating environment applicability

Here’s an example of our current duplication:


REQ-101: User authentication via LDAP (on-prem)
REQ-102: User authentication via SSO (cloud)

Both trace to the same test cases and user stories, making our traceability matrix messy. How are others handling environment-specific requirement variations without losing traceability?

2

Based on your authentication vs data residency examples, here’s a comprehensive approach that handles both scenarios effectively.

Core Principle: Use a Canonical Requirement Per Business Behavior Create one requirement issue that captures the business need independent of environment. This is your source of truth for what the system must accomplish, not how it accomplishes it. Your requirement title should describe the capability, not the implementation: “Users must authenticate securely” rather than “Implement LDAP authentication.”

Modeling Environment Applicability in Custom Fields For requirements where implementation varies but acceptance criteria are similar:

  1. Add Environment Scope Field (Multi-Select)

    • Values: On-Premises, Cloud, Hybrid
    • Required field that forces explicit environment applicability
    • Visible on requirement cards and in JQL queries

  2. Add Implementation Variance Field (Single Select)

    • Values: Identical, Minor Variance, Major Variance
    • Helps determine if child issues are needed
    • Filters requirements needing deeper environment-specific analysis

  3. Add Environment Implementation Notes (Text Area)

    • Use a structured format:
    
On-Premises Implementation:
- LDAP integration with Active Directory
- Local credential storage
- Session timeout: 30 minutes

Cloud Implementation:
- SSO via OAuth 2.0 (Okta)
- Token-based authentication
- Session timeout: 60 minutes

This approach works well for your authentication example where the business requirement (secure authentication) is the same, but technical implementation differs. Test cases can link to the parent requirement and use environment-specific test data or configurations.

Using Child Issues for Truly Divergent Environment Behavior When acceptance criteria, testing approach, or technical architecture fundamentally differs (like your data residency example), create child issues:

Parent Requirement: “Customer data must comply with geographic residency regulations”

  • Environment Scope: On-Premises, Cloud
  • Implementation Variance: Major Variance
  • Status: Drives overall completion based on child completion

Child Issue 1: “On-Premises: Data residency via physical server location controls”

  • Acceptance Criteria:
    • Servers physically located in customer-specified region
    • Network traffic restricted to regional data center
    • Backup storage within same geographic boundary
  • Test Cases: Physical audit procedures, network trace validation

Child Issue 2: “Cloud: Data residency via AWS region selection and sovereignty settings”

  • Acceptance Criteria:
    • AWS region configured per customer contract
    • S3 bucket region lock enabled
    • Cross-region replication disabled
    • CloudTrail logging for data access audit
  • Test Cases: AWS configuration validation, API-based region verification

The children have completely different acceptance criteria, testing approaches, and technical implementations. They’re genuinely separate requirements from a development and QA perspective, but logically grouped under the business need.

Traceability Matrix Impact With this hybrid approach, your traceability becomes:

  • User Story → Parent Requirement → Child Requirements (if needed) → Test Cases
  • Test cases link to the most specific requirement level (parent for minor variance, child for major variance)
  • JQL queries can roll up coverage: “Show me all requirements with Cloud environment scope and their test coverage”
  • Reports show parent requirement status as aggregate of children when children exist

Decision Criteria for Your Team

Use Custom Fields Only when:

  • Business logic and acceptance criteria are essentially the same
  • Testing approach is similar (same test cases, different test data)
  • Implementation notes can adequately capture differences
  • Development work happens in the same codebase/branch
  • Examples: Authentication methods, UI theme variations, regional date formats

Use Child Issues when:

  • Acceptance criteria differ substantially
  • Testing requires different test cases or testing tools
  • Development happens in separate code modules or branches
  • Separate technical reviews or approvals needed
  • Examples: Data residency, compliance certifications, infrastructure requirements

Workflow Integration Add a workflow validator that checks:

  • If “Implementation Variance” = “Major Variance”, require at least one child issue per environment in “Environment Scope”
  • If no child issues exist, require “Environment Implementation Notes” to be populated
  • This enforces your standard and prevents incomplete requirement specifications

Practical Example for Your Authentication Requirement Since authentication is conceptually the same (verify user identity and establish session), use the custom field approach:

REQ-101: “Users must authenticate securely before accessing the application”

  • Environment Scope: On-Premises, Cloud

  • Implementation Variance: Minor Variance

  • Environment Implementation Notes:

    
On-Premises: LDAP integration
Cloud: SSO via OAuth 2.0
Both: Multi-factor authentication optional, session management per security policy

  • Test Cases: TC-AUTH-001 (LDAP login flow), TC-AUTH-002 (SSO login flow), TC-AUTH-003 (Session timeout)

The test cases reference the same requirement but have environment-specific test data in their configurations. Your traceability matrix shows one requirement with multiple test cases, clearly indicating which tests apply to which environments via labels or test case custom fields.

This approach eliminates your REQ-101/REQ-102 duplication while maintaining clear traceability and supporting both simple and complex environment variations.

3

For truly divergent behavior like data residency, use child issues under a parent requirement. The parent describes the business need (“Customer data must remain in specified geographic region”), and children describe environment-specific implementations (“On-Prem: Physical server location controls” vs “Cloud: AWS region selection and data sovereignty settings”). This preserves the logical grouping while allowing different test approaches and acceptance criteria per environment.

4

We use approach #3 with good success. Create one canonical requirement that describes the behavior (“Users must authenticate securely”), then add a multi-select custom field called “Applicable Environments” with values: On-Prem, Cloud, Hybrid. Add another field “Environment Notes” to capture specific implementation details. This keeps traceability clean since test cases link to one requirement, and environment-specific test configurations handle the variations.

5

One thing to consider: how does this affect your test automation? We struggled when requirements were split because our test framework needed to know which environment to target. We ended up using labels like “env-onprem” and “env-cloud” on requirements and test cases, which our CI/CD pipeline reads to determine which tests to run in each environment. Works well with either the custom field or child issue approach.

6

That makes sense for minor variations. But what about when the implementation is fundamentally different? For example, our data residency requirements for cloud involve completely different technical controls than on-prem. Would you still use one requirement with notes, or split into child issues?

7

We’ve tried all three approaches over the past year. Here’s what worked for us: use a decision tree based on the degree of divergence. For your authentication example, I’d use a single canonical requirement because the business need is identical even though implementation differs. For data residency, use child issues because acceptance criteria and testing are fundamentally different.