Add EnvManager

[mokagio]

What does it do?

Adds EnvManager, a helper class for loading .env files and accessing environment variables with clear error messages.

Originally developed in the Gravatar-SDK-iOS repo, then adapted for the release toolkit.

Note

The diff is big, but it's 2/3 tests

• Loads env vars from a .env file via Dotenv at initialization
• get_required_env!(key) returns the value or raises with a context-aware message (CI vs. local, file exists vs. missing)
• require_env_vars!(*keys) validates multiple keys at once, failing fast on the first missing one — accepts both varargs and arrays
• Warns at init when the .env file is missing (suppressed on CI)
• Instance-based design with class-level convenience methods (set_up, get_required_env!, reset!, configured?) for backward compatibility
• Error and warning output decoupled via injectable lambdas, defaulting to Fastlane UI
• CI environment helpers (build_number, branch_name, commit_hash, pull_request_number, pr_number_or_branch_name)

Example adoption

See Automattic/simplenote-ios#1742 for an example of migrating a project from a local EnvManager copy to the release-toolkit version.

Checklist before requesting a review

• Run bundle exec rubocop to test for code style violations and recommendations
• Add Unit Tests (aka specs/*_spec.rb) if applicable
• Run bundle exec rspec to run the whole test suite and ensure all your tests pass
• Make sure you added an entry in the CHANGELOG.md file to describe your changes under the appropriate existing ### subsection of the existing ## Trunk section.
• If applicable, add an entry in the MIGRATION.md file to describe how the changes will affect the migration from the previous major version and what the clients will need to change and consider.

[dangermattic]

	1 Warning
⚠️	This PR is larger than 500 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

Generated by 🚫 Danger

[Copilot]

Pull request overview

Adds a new EnvManager utility to the release-toolkit Fastlane plugin to load .env files and provide clearer, context-aware environment variable access (including CI metadata helpers), along with an accompanying RSpec test suite.

Changes:

• Introduce EnvManager class with instance API plus class-level convenience methods (set_up, get_required_env!, require_env_vars!, reset!, configured?).
• Add comprehensive specs covering initialization behavior, required env var access, and CI helper methods.
• Update plugin autoload glob to include the new env_manager directory and document the addition in CHANGELOG.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
lib/fastlane/plugin/wpmreleasetoolkit/env_manager/env_manager.rb	Adds the EnvManager implementation (Dotenv loading, error/warning output injection, CI helpers, class-level delegation).
spec/env_manager_spec.rb	Adds specs validating EnvManager behavior and error messaging.
lib/fastlane/plugin/wpmreleasetoolkit.rb	Ensures the plugin loads Ruby files from the new env_manager directory.
CHANGELOG.md	Notes the new feature in Trunk.

---

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

[Copilot]

.set_up relies on default_print_error_lambda raising to prevent reconfiguration, but if a caller injects a non-raising lambda the method will continue and overwrite @default anyway. Make this guard deterministic by raising/returning immediately after emitting the error.

Suggested change

	default_print_error_lambda.call('EnvManager is already configured. Call `EnvManager.reset!` before calling `EnvManager.set_up(...)` again.') if configured?
	if configured?
	default_print_error_lambda.call('EnvManager is already configured. Call `EnvManager.reset!` before calling `EnvManager.set_up(...)` again.')
	return @default
	end

[Copilot]

default! calls default_print_error_lambda but does not raise/return afterward; with a non-raising lambda this will return nil and callers will fail later with less clear errors. Consider raising a specific exception (or returning after calling the lambda) so the failure mode is consistent.

Suggested change

	default_print_error_lambda.call('EnvManager is not configured. Call `EnvManager.set_up(...)` first.')
	message = 'EnvManager is not configured. Call `EnvManager.set_up(...)` first.'
	default_print_error_lambda.call(message)
	raise RuntimeError, message

[Copilot]

get_required_env! assumes @print_error_lambda will raise; otherwise execution continues to ENV.fetch(key) (raising KeyError) and the error message paths above are bypassed. To keep behavior consistent with the method’s bang semantics, explicitly raise (or return after a raising call) when the key is missing or the value is empty.

Suggested change

	if running_on_ci?
	@print_error_lambda.call(message)
	elsif File.exist?(@env_path)
	@print_error_lambda.call("#{message} Consider adding it to #{@env_path}.")
	else
	env_file_dir = File.dirname(@env_path)
	env_file_name = File.basename(@env_path)
	@print_error_lambda.call <<~MSG
	#{env_file_name} not found in #{env_file_dir} while looking for env var #{key}.
	Please copy #{@env_example_path} to #{@env_path} and fill in the value for #{key}.
	mkdir -p #{env_file_dir} && cp #{@env_example_path} #{@env_path}
	MSG
	end
	end
	value = ENV.fetch(key)
	@print_error_lambda.call("Env var for key #{key} is set but empty. Please set a value for #{key}.") if value.to_s.empty?
	error_message =
	if running_on_ci?
	message
	elsif File.exist?(@env_path)
	"#{message} Consider adding it to #{@env_path}."
	else
	env_file_dir = File.dirname(@env_path)
	env_file_name = File.basename(@env_path)
	<<~MSG
	#{env_file_name} not found in #{env_file_dir} while looking for env var #{key}.
	Please copy #{@env_example_path} to #{@env_path} and fill in the value for #{key}.
	mkdir -p #{env_file_dir} && cp #{@env_example_path} #{@env_path}
	MSG
	end
	@print_error_lambda.call(error_message)
	raise KeyError, error_message
	end
	value = ENV.fetch(key)
	if value.to_s.empty?
	message = "Env var for key #{key} is set but empty. Please set a value for #{key}."
	@print_error_lambda.call(message)
	raise ArgumentError, message
	end

[Copilot]

The setup instructions include a shell command built from interpolated paths. If any path contains spaces or shell metacharacters, the copy/paste command can break or behave unexpectedly. Quote/escape the paths in the suggested command (e.g., via Shellwords.escape).

[Copilot]

This example is labeled as testing .require_env_vars! delegation, but it only calls .get_required_env! and never exercises .require_env_vars!. Update the expectation to call described_class.require_env_vars!(...) so the delegation is actually covered.

Suggested change

	expect(described_class.get_required_env!('CK1')).to eq('v1')
	expect(described_class.get_required_env!('CK2')).to eq('v2')
	expect { described_class.require_env_vars!('CK1', 'CK2') }.not_to raise_error

[Copilot]

The comment above all_classes says it returns files from only actions, helper, and models, but the glob also includes versioning and now env_manager. Update the comment to reflect the actual directories being loaded.

Suggested change

	# Return all .rb files inside the "actions", "helper" and "models" directories
	# Return all .rb files inside the "actions", "env_manager", "helper", "models", and "versioning" directories

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

---

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

[iangmaia]

I understand this won't necessarily break compatibility (unless it conflicts to top level EnvManager per repo, but we could fix that here as pointed out above).
But maybe we could still provide some migration instructions for repos, for the sake of clarity?

[mokagio]

Once EnvManager is namespaced (#3 / per discussion above), there is no class collision risk, so I think we can keep the migration nudge to a single sentence in the existing entry rather than a dedicated section. Updated in cbecee8 to Add Fastlane::Wpmreleasetoolkit::EnvManager … Repos that maintain their own EnvManager can switch to this centralized implementation. WDYT?

[iangmaia]

Works for me 👍

[mokagio]

Thanks @iangmaia ! I think I addressed all your suggestions now.