docs: document "remote stacks" approach #85
Conversation
By default, this module assumes all stacks are in the same repo as the
stack with the module instance.
What if users want to use this module to manage stacks in _another
repo_? We had this use case and came up with a "remote stacks" approach.
It would be great to document this approach for other users.
This PR will document the remote stacks approach in the README. The
example looks like this:
```text
this-repo
├── remote-stacks
│ └── other-repo
│ └── other-repo-random-pet
│ └── stack.yaml
└── stacks
└── spacelift-automation
├── main.tf
├── stack.yaml
└── versions.tofu
```
```yaml
# this-repo/remote-stacks/other-repo/other-repo-random-pet/stack.yaml
stack_settings:
project_root: stacks/random-pet
```
```text
other-repo
└── stacks
└── random-pet
├── main.tf
└── versions.tofu
```
Note that the README recommends that the remote stacks directory should
_not_ be nested inside of another stack. This is because of the changes
to globbing behavior introduced in masterpointio#80 and module v1.5.0. The new
behavior introduced some unexpected changes for our repo because we had
a remote stacks directory nested inside our stacks directory, like this
basically:
```hcl
# this-repo/app/stacks/spacelift-automation/main.tf
module "spacelift_automation_for_stacks_in_this_repo" {
source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git"
all_root_modules_enabled = true
repository = "this-repo"
root_module_structure = "SingleInstance"
root_modules_path = "../../../app/stacks"
}
module "spacelift_automation_for_stacks_in_other_repo" {
source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git"
all_root_modules_enabled = true
repository = "other-repo"
root_module_structure = "SingleInstance"
root_modules_path = "../../../app/stacks/spacelift-automation/remote-stacks/other-repo"
}
```
After updating to module v1.5.0, the `spacelift_automation_this_repo`
module instance started picking up the `stack.yaml` files in the nested
`remote-stacks` subdirectory.
The easiest solution is just to not nest the remote stacks dir. Another
solution is to set `all_root_modules_enabled = false` and then add the
stacks in the repo to `enabled_root_modules`. This of course means that
new stacks added to `app/stacks/new-stack-name/stack.yaml` have to be
added to `enabled_root_modules` to be detected.
```hcl
# this-repo/app/stacks/spacelift-automation/main.tf
module "spacelift_automation_for_stacks_in_this_repo" {
source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git"
all_root_modules_enabled = false
enabled_root_modules = [
"development",
"production",
"spacelift-automation",
]
repository = "this-repo"
root_module_structure = "SingleInstance"
root_modules_path = "../../../app/stacks"
}
module "spacelift_automation_for_stacks_in_other_repo" {
source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git"
all_root_modules_enabled = true
repository = "other-repo"
root_module_structure = "SingleInstance"
root_modules_path = "../../../app/stacks/spacelift-automation/remote-stacks/other-repo"
}
```
WalkthroughAdds a new README section titled “What if my stacks are in another repo?” describing how to manage Spacelift stacks located in a separate Git repository. It outlines repository structure, access requirements, the use of a remote-stacks directory (with placement caveats), example layouts, stack.yaml project_root guidance, and Terraform module configuration examples referencing both local and remote repositories. No code or API changes; documentation only. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested reviewers
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
Status, Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
README.md (6)
247-247: Fix typo and casing.“here's now it might look” ➜ “here’s how it might look”; also capitalize “Spacelift Automation” for consistency with the rest of the README.
- ... For example, here's now it might look for a repo named ... + ... For example, here’s how it might look for a repo named ... - ... within the Spacelift automation stack directory ... + ... within the Spacelift Automation stack directory ...
272-289: Pin the module version (prefer registry) to ensure reproducibility.Using a floating Git source can lead to surprise changes. Recommend the Terraform Registry with a pinned version, or pin a Git tag/commit via ?ref.
- module "spacelift_automation_this_repo" { - source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git" + module "spacelift_automation_this_repo" { + # Prefer the Registry and pin a version + source = "masterpointio/automation/spacelift" + version = "~> 1.5" ... - } + }Alternative (if you must keep Git):
- source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git" + source = "git::https://github.com/masterpointio/terraform-spacelift-automation.git?ref=v1.5.0"
277-281: Double‑check root_modules_path semantics; consider dropping “../../”.The Inputs table documents root_modules_path as “relative to the root of the repository.” If that’s the case, the examples should be repo‑root‑relative (e.g., "stacks" and "remote-stacks/other-repo") instead of pathing relative to the module file’s folder.
- root_modules_path = "../../stacks" + root_modules_path = "stacks" ... - root_modules_path = "../../remote-stacks/other-repo" + root_modules_path = "remote-stacks/other-repo"If the module intentionally resolves relative to the module call site, ignore this suggestion—but then consider clarifying that behavior here to avoid confusion.
Also applies to: 285-289
236-244: Clarify why the remote repo should not contain a stack.yaml.Add one sentence explaining that stack.yaml lives in the host repo to avoid duplicate detection and to keep Spacelift config co-located with the automation module.
- There should not be a `stack.yaml` file in the other repo. + There should not be a `stack.yaml` file in the other repo, since the Spacelift configuration for remote stacks is defined in this repo to prevent duplicate discovery and to keep all Stack config alongside the automation module.
262-268: Include “kind” for consistency with earlier examples (optional).Earlier you showed kind: StackConfigV1. Consider including it here so readers can copy/paste a fully valid example.
# this-repo/remote-stacks/other-repo/other-repo-random-pet/stack.yaml - stack_settings: + kind: StackConfigV1 + stack_settings: project_root: stacks/random-pet
246-261: Document the alternative mitigation for nested remote-stacks (enabled_root_modules).Since #80 changed globbing, add a short note showing the second mitigation (set all_root_modules_enabled = false and enumerate enabled_root_modules) with its tradeoff.
- Note: If you must nest
remote-stacksunder the Spacelift Automation stack, set:- all_root_modules_enabled = false
- enabled_root_modules = ["spacelift-automation", "remote-stacks/other-repo"]
- Tradeoff: new stacks won’t be auto-discovered—you must add them to
enabled_root_modules.Happy to add this snippet where you’d like it and adjust wording for your style guide. </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: .coderabbit.yaml** **Review profile: CHILL** **Plan: Pro** **💡 Knowledge Base configuration:** - MCP integration is disabled by default for public repositories - Jira integration is disabled by default for public repositories - Linear integration is disabled by default for public repositories You can enable these sources in your CodeRabbit configuration. <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 0f35dae7f0beff4df86488b0e5aafff765c6a6b1 and c0fc07dd57dcc69f339b7ed3c3a750276a62d493. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `README.md` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (1)</summary> <details> <summary>📚 Learning: 2025-05-12T15:44:10.001Z</summary>Learnt from: gberenice
PR: masterpointio/terraform-users-groups-automation-googleworkspace#1
File: examples/import-existing-org/imports.tf:7-7
Timestamp: 2025-05-12T15:44:10.001Z
Learning: In Terraform, local variables defined in one .tf file are available throughout all other .tf files in the same module directory, which allows for referencing locals across different files.**Applied to files:** - `README.md` </details> </details> </details> <details> <summary>🔇 Additional comments (1)</summary><blockquote> <details> <summary>README.md (1)</summary> `232-289`: **Nice addition — clear, actionable guidance for “remote stacks.”** The new section is helpful and aligns with how the module models stacks across repos. The stepwise walkthrough, example trees, and configuration blocks will save users time. </details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
The config in `.trunk/configs/.markdownlint.yaml` has `strict: false` for `MD013`, but the GitHub Actions lint job is still erroring. Error: ``` README.md:247:0 247:0 low Line length markdownlint/MD013 ``` fix: ```sh prettier --print-width 350 --prose-wrap always --write README.md ```
|
Thanks for highlighting that nested glob pattern. I'm going to think more on that. This PR is great. I'll leave it to Matt to review further. |
Gowiem
left a comment
Gowiem
left a comment
There was a problem hiding this comment.
@br3ndonland this is an awesome FAQ addition -- thank you for circling back around to this and contributing it. Love seeing previous clients contribute to our OSS ❤️
Few small requests and then let's 
!
Co-authored-by: Matt Gowie <[email protected]>
gberenice
left a comment
gberenice
left a comment
There was a problem hiding this comment.
Thanks a lot @br3ndonland!
I've fixed the tests and now this is good to 🚢
4 participants
Description
By default, this module assumes all stacks are in the same repo as the stack with the module instance.
What if the module needs to manage stacks in another repo? We had this use case and developed a "remote stacks" approach. Here's @Gowiem to explain:
It would be great to document this approach for other users.
Changes
This PR will document the remote stacks approach in the README. The example looks like this:
Note that the README recommends that the remote stacks directory should not be nested inside of another stack. This is because of the changes to globbing behavior introduced in #80 and module v1.5.0. The new behavior introduced some unexpected changes for our repo because we had a remote stacks directory nested inside our stacks directory, like this basically:
After updating to module v1.5.0, the
spacelift_automation_this_repomodule instance started picking up thestack.yamlfiles in the nestedremote-stackssubdirectory.The easiest solution is just to not nest the remote stacks dir. Another solution is to set
all_root_modules_enabled = falseand then add the stacks in the repo toenabled_root_modules. This of course means that new stacks added toapp/stacks/new-stack-name/stack.yamlhave to be added toenabled_root_modulesto be detected.Related
Summary by CodeRabbit