feat: pass Graph client timeout through Connect-Maester

[blindzero]

📑 Description

Closes #2079

Long-running tests can exceed the Microsoft Graph PowerShell SDK's default HTTP client timeout. This PR adds an optional -ClientTimeout parameter to Connect-Maester and forwards it directly to Connect-MgGraph.

Connect-Maester -ClientTimeout 900
Invoke-Maester -IncludeLongRunning

Callers that manage their own Graph connection, including those using Invoke-Maester -SkipGraphConnect, can use the native SDK parameter directly:

Connect-MgGraph -Scopes (Get-MtGraphScope) -ClientTimeout 900
Invoke-Maester -SkipGraphConnect -IncludeLongRunning

Behavior

• No Maester-specific timeout default is introduced.
• When -ClientTimeout is omitted, Connect-MgGraph uses its existing SDK default.
• There is no maester-config.json timeout setting.
• Invoke-Maester does not read or mutate the global Graph request context.
• Timeout is connection-wide because Invoke-MgGraphRequest does not expose a per-request timeout.

✅ Checks

• Focused Connect-Maester tests: 11 passed
• PSScriptAnalyzer tests: 981 passed
• Full PowerShell suite: 10,346 passed, 0 failed
• Aggregate diff checked against current main
• Documentation updated without editing generated command docs

Summary by CodeRabbit

• New Features

  • Added an optional ClientTimeout setting to configure Microsoft Graph request timeouts when connecting.
  • Supports timeout values up to 900 seconds for long-running operations.

• Documentation

  • Added FAQ guidance for Microsoft Graph timeout failures, default behavior, and timeout configuration.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: bacc0d2b-1893-432d-b1e4-c1ecb94a20f1

📥 Commits

Reviewing files that changed from the base of the PR and between dbf1a08 and 1ca74b4.

📒 Files selected for processing (3)

• powershell/public/Connect-Maester.ps1
• powershell/tests/functions/Connect-Maester.Tests.ps1
• website/docs/faq.md

---

📝 Walkthrough

Walkthrough

Connect-Maester adds an optional ClientTimeout parameter for Microsoft Graph requests. Explicit values are forwarded to Connect-MgGraph, while omitted values use the SDK default. Tests cover forwarding behavior, and the FAQ documents configuration options.

Changes

Microsoft Graph client timeout

Layer / File(s)	Summary
Timeout parameter and Graph forwarding powershell/public/Connect-Maester.ps1, powershell/tests/functions/Connect-Maester.Tests.ps1	Connect-Maester accepts an optional double ClientTimeout and forwards explicit values to Connect-MgGraph. Tests cover parameter type, conditional forwarding, and non-Graph services.
Timeout configuration guidance website/docs/faq.md	The FAQ documents Microsoft Graph timeout failures, ClientTimeout configuration, direct Graph connections, SkipGraphConnect, and default timeout behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 1ca74

The PR adds an optional, run-scoped Graph timeout override while preserving existing defaults and restoring the prior timeout afterward. Documentation and tests are included, and no actionable merge-blocking risk remains beyond normal checks and review.

Suggested labels: enhancement

Suggested reviewers: soulemike

Sequence Diagram(s)

sequenceDiagram
  participant MaesterCaller
  participant ConnectMaester
  participant ConnectMgGraph
  MaesterCaller->>ConnectMaester: provide optional ClientTimeout
  ConnectMaester->>ConnectMgGraph: forward ClientTimeout when supplied
  ConnectMgGraph-->>ConnectMaester: establish Graph connection

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #2079 by providing documented timeout configuration for long-running Microsoft Graph tests through Connect-Maester or Connect-MgGraph.
Out of Scope Changes check	✅ Passed	The changes are focused on Graph client timeout support, related tests, and documentation, with no unrelated code changes identified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly describes the main change: passing the Graph client timeout through Connect-Maester.
Description check	✅ Passed	The description explains the change, usage, behavior, issue reference, documentation updates, and test results.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with 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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@website/docs/configuration/overview.md`:
- Line 92: Update the GraphRequestTimeoutSeconds entry in the configuration
table to use complete sentences and explicitly document that accepted values
range from 1 to 3600 seconds, while retaining the existing override guidance for
Invoke-Maester.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e50ad7dc-ad97-4122-b2a6-f177bdb60e9d

📥 Commits

Reviewing files that changed from the base of the PR and between f18dd1c and 0c1e7a8.

📒 Files selected for processing (6)

• .gitignore
• powershell/public/Invoke-Maester.ps1
• powershell/tests/functions/Invoke-Maester.Tests.ps1
• tests/maester-config.json
• website/docs/configuration/overview.md
• website/docs/faq.md

[Copilot]

Pull request overview

Adds a configurable Microsoft Graph request timeout to address failures in long-running Maester tests that can exceed the Graph SDK’s default 300s timeout, with support for config-based defaults and an Invoke-Maester CLI override.

Changes:

• Introduces -GraphRequestTimeoutSeconds on Invoke-Maester and applies it via Set-MgRequestContext -ClientTimeout.
• Adds GlobalSettings.GraphRequestTimeoutSeconds (default 300) to the main tests/maester-config.json, with override behavior covered by new unit tests.
• Updates website documentation (FAQ + configuration overview) and ignores tests/Custom/maester-config.json to prevent committing org-specific overrides.

Reviewed changes

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

Show a summary per file

File	Description
website/docs/faq.md	Documents how to resolve Graph timeout failures using the new parameter or custom config.
website/docs/configuration/overview.md	Lists GraphRequestTimeoutSeconds as an available global setting.
tests/maester-config.json	Adds the new setting to the default config template with a default of 300 seconds.
powershell/tests/functions/Invoke-Maester.Tests.ps1	Adds unit tests covering precedence and validation behavior for the timeout setting.
powershell/public/Invoke-Maester.ps1	Implements the new parameter and resolves/validates config + parameter precedence before running tests.
.gitignore	Prevents committing tests/Custom/maester-config.json (user/org-specific overrides).

---

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

[merill]

@blindzero thank you for raising this PR, really appreciate the work done here.

Given our imminent re-write in Maester 3.0, I want to avoid adding too much complexity to Invoke-Maester.

So I have switched to a simpler workaround using Connect-Maester and passing the ClientTimeout directly.

The ideal config I want to have is for the timeout to be defined at a per test level and then we can have the Maester 3.0 engine dynamically setting the timeout on an as-needed basis.

Would you be able to test the latest PR and let me know if that solves your current issue with the timeout?

[merill]

Going ahead and merging since I haven't heard back in a few days.