feat(riff-raff-generator)!: Support multiple Riff-Raff projects

[akash1810]

Note

Requires #2870.

What does this change?

Looking in guardian/riffraff-platform we have multiple repositories that deploy multiple RIff-Raff projects. This change updates the riff-raff.yaml generator to support these repositories. To do this, a new optional riffRaffProjectName property¹ is added to GuStack. As a side benefit, when set, a gu:riff-raff-project tag is also added to all resources. This tag can be used to pull deployment information into the Availability dashboard.

In the below example, the following files will be generated:

• /path/to/cdk.out/playground::core-infra/riff-raff.yaml
• /path/to/cdk.out/playground::api/riff-raff.yaml

class CoreInfraStack extends GuStack {}
class MyApi extends GuStack {}

const app = new App();

new CoreInfraStack(app, "core-infra", {
  stack: "playground",
  stage: "INFRA",
  riffRaffProjectName: "playground::core-infra", // <-- NEW
});

new MyApi(app, "api-code", {
  stack: "playground",
  stage: "CODE",
  riffRaffProjectName: "playground::api", // <-- NEW
});

new MyApi(app, "api-prod", {
  stack: "playground",
  stage: "PROD",
  riffRaffProjectName: "playground::api", // <-- NEW
});

Note

#2814 and #2815 offer alternative implementations of this feature. I think this version has the cleanest API for users as it is a no-op by default; if riffRaffProjectName is not set, the usual /path/to/cdk.out/riff-raff.yaml is still created.

How to test

See added unit tests.

How can we measure success?

Supporting more use-cases across the department.

Have we considered potential risks?

There are some breaking changes to the RiffRaffYamlFile class. Specifically, the riffRaffYaml property has been removed and the toYAML function signature has changed. Using a GitHub search, we can see there isn't much usage of these:

• riffRaffYaml usage
• toYAML usage

The migration path has been documented.

Checklist

• I have listed any breaking changes, along with a migration path ²
• I have updated the documentation as required for the described changes ³

Footnotes

1. The property is currently optional after https://github.com/guardian/riff-raff/pull/1378. ↩

2. Consider whether this is something that will mean changes to projects that have already been migrated, or to the CDK CLI tool. If changes are required, consider adding a checklist here and/or linking to related PRs. ↩

3. If you are adding a new construct or pattern, has new documentation been added? If you are amending defaults or changing behaviour, are the existing docs still valid? ↩

[changeset-bot]

🦋 Changeset detected

Latest commit: f8f2436

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@guardian/cdk	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds first-class support for repositories that deploy multiple Riff-Raff projects by grouping GuStacks by an optional riffRaffProjectName, generating one riff-raff.yaml per project (and tagging resources accordingly).

Changes:

• Add optional riffRaffProjectName to GuStackProps and apply a gu:riff-raff-project tag to all resources when set.
• Update RiffRaffYamlFile to build a per-project configuration map and synthesize multiple riff-raff.yaml files into per-project subdirectories.
• Add/extend unit tests and update documentation + changesets for the new behavior and breaking API adjustments.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/constructs/core/stack.ts	Introduces riffRaffProjectName prop and applies gu:riff-raff-project tagging.
src/riff-raff-yaml-file/index.ts	Refactors generator to produce per-project configurations and write multiple YAML outputs.
src/riff-raff-yaml-file/group-by.ts	Adds grouping by riffRaffProjectName with a default “unknown” project key.
src/riff-raff-yaml-file/types.ts	Adds RiffRaffProjectName alias and UnknownRiffRaffProjectName constant.
src/riff-raff-yaml-file/index.test.ts	Updates tests for new configuration API and adds multi-project test coverage.
src/riff-raff-yaml-file/README.md	Documents multi-project generation and migration path for the breaking API change.
src/utils/array.test.ts	Extends groupBy test coverage around undefined grouping keys/defaulting.
.changeset/thirty-schools-pay.md	Minor release note for new GuStackProps field/tagging behavior.
.changeset/eleven-animals-pick.md	Major release note documenting breaking RiffRaffYamlFile API changes.

Comments suppressed due to low confidence (1)

src/riff-raff-yaml-file/index.ts:64

• For consistency/readability with the new RiffRaffProjectName type alias, MissingStack.riffRaffProjectName should use RiffRaffProjectName instead of plain string (it’s part of the structured “missing stacks” diagnostics).

interface MissingStack {
  riffRaffProjectName: string;
  className: ClassName;
  stack: StackTag;
  stage: StageTag;
  region: Region;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.