BED-9680: optimize environment collection

[jaredcatkinson]

Summary

• capture GitHub-reported branch and environment totals from the repository GraphQL query
• skip per-repository environment REST collection when GraphQL reports zero environments
• expose branch_count and environment_count on GH_Repository for collection completeness validation

Testing

• uv run pytest tests/test_repository_rulesets.py tests/test_environment_resources.py
• uv run pytest

Notes

• This branch is stacked on the currently open GitHub Actions modeling work through BED-9678.

Summary by CodeRabbit

• New Features

  • Added workflow-to-environment relationships for jobs authorized to request OIDC tokens.
  • Added repository branch and environment totals.
  • Added workflow-job access relationships for organization, repository, and environment secrets.
  • Added GitHub deployment type and Enterprise Server version details.

• Improvements

  • Permissions are now represented as structured scope:access lists.
  • Runner discovery is more consistent and retains repository runners when organization details are unavailable.
  • Environment collection skips repositories with no environments.

• Documentation

  • Updated GitHub entity schemas and relationship diagrams to reflect current behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: ae8e2b32-bba7-4cf3-835a-e830c6bd8684

📥 Commits

Reviewing files that changed from the base of the PR and between 033a7ef and 2575ed4.

📒 Files selected for processing (41)

• descriptions/edges/GH_CanRequestOIDCTokenFor.md
• descriptions/nodes/GH_AppInstallation.md
• descriptions/nodes/GH_Enterprise.md
• descriptions/nodes/GH_EnterpriseRunner.md
• descriptions/nodes/GH_Environment.md
• descriptions/nodes/GH_EnvironmentSecret.md
• descriptions/nodes/GH_OrgRunner.md
• descriptions/nodes/GH_OrgSecret.md
• descriptions/nodes/GH_Organization.md
• descriptions/nodes/GH_PersonalAccessToken.md
• descriptions/nodes/GH_PersonalAccessTokenRequest.md
• descriptions/nodes/GH_RepoRunner.md
• descriptions/nodes/GH_RepoSecret.md
• descriptions/nodes/GH_Repository.md
• descriptions/nodes/GH_Runner.md
• descriptions/nodes/GH_Workflow.md
• descriptions/nodes/GH_WorkflowJob.md
• extension/privilege_zone_rules/t0-app-installations-all-repos.json
• extension/privilege_zone_rules/t0-apps-all-repos.json
• extension/privilege_zone_rules/t0-pats-all-repos.json
• extension/schema.json
• scripts/generate_gh_description_docs.py
• src/openhound_github/graphql.py
• src/openhound_github/kinds/edges.py
• src/openhound_github/lookup.py
• src/openhound_github/models/app_installation.py
• src/openhound_github/models/permissions.py
• src/openhound_github/models/personal_access_token.py
• src/openhound_github/models/personal_access_token_request.py
• src/openhound_github/models/repository.py
• src/openhound_github/models/workflow.py
• src/openhound_github/models/workflow_job.py
• src/openhound_github/resources/organization.py
• src/openhound_github/transforms.py
• tests/test_credential_permission_models.py
• tests/test_environment_resources.py
• tests/test_repository_rulesets.py
• tests/test_runner_models.py
• tests/test_workflow_interception_path.py
• tests/test_workflow_model.py
• tests/test_workflow_resources.py

💤 Files with no reviewable changes (3)

• descriptions/nodes/GH_EnterpriseRunner.md
• descriptions/nodes/GH_RepoRunner.md
• descriptions/nodes/GH_OrgRunner.md

Included review availability: 3 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

Walkthrough

The change adds workflow-job OIDC capability edges, normalizes credential permissions, adds repository branch and environment counts, improves environment and runner lookup behavior, updates privilege rules, and refreshes GitHub model documentation.

Changes

Credential permissions

Layer / File(s)	Summary
Permission normalization and credential contracts src/openhound_github/models/*, descriptions/nodes/GH_AppInstallation.md, descriptions/nodes/GH_PersonalAccessToken*.md	Permission payloads now use normalized scope:access lists across app installations, personal access tokens, requests, and workflows.
Permission-based privilege rules extension/privilege_zone_rules/*	Rules now match permission entries ending in :write.
Workflow permission lookup behavior src/openhound_github/lookup.py, src/openhound_github/resources/organization.py, tests/test_workflow_resources.py, tests/test_credential_permission_models.py	Lookups prefer populated values and cache failed repository permission requests as empty results. Tests cover cache separation and normalization.

Workflow OIDC capability

Layer / File(s)	Summary
OIDC edge contract and documentation extension/schema.json, src/openhound_github/kinds/edges.py, descriptions/edges/*, descriptions/nodes/GH_Environment.md, descriptions/nodes/GH_WorkflowJob.md	The traversable GH_CanRequestOIDCTokenFor relationship is registered and documented.
OIDC and secret edge generation src/openhound_github/models/workflow_job.py, descriptions/nodes/GH_*Secret.md	Eligible jobs emit OIDC edges for persisted environments. Secret-query values are escaped.
OIDC and query validation tests/test_workflow_model.py, tests/test_workflow_interception_path.py	Tests cover permissions, environments, edge isolation, idempotency, environment targeting, and escaped values.

Repository counts and environments

Layer / File(s)	Summary
Repository count contracts and GraphQL data src/openhound_github/graphql.py, src/openhound_github/models/repository.py, descriptions/nodes/GH_Repository.md	Repository models and GraphQL queries now expose branch and environment totals.
Repository count lookup and storage src/openhound_github/lookup.py, src/openhound_github/transforms.py	Count lookups and idempotent table migrations support nullable totals.
Environment collection wiring src/openhound_github/resources/organization.py, tests/test_environment_resources.py	Environment collection uses GraphQL repository records and skips repositories with zero environments.
Repository count validation tests/test_repository_rulesets.py	Tests cover flattening, node propagation, nullable results, and lookup behavior.

Runner resolution

Layer / File(s)	Summary
Runner source precedence and ordering src/openhound_github/lookup.py	Runner matches now use source precedence, deduplication, and deterministic ordering.
Runner lookup regression coverage tests/test_runner_models.py	Tests verify repository runners remain available when organization data is missing.
Runner relationship diagrams descriptions/nodes/GH_*Runner.md	Runner diagrams now reflect the current workflow-job and runner relationships.

Platform metadata documentation

Layer / File(s)	Summary
Deployment and workflow property documentation descriptions/nodes/GH_Enterprise.md, descriptions/nodes/GH_Organization.md, descriptions/nodes/GH_Workflow.md	Documentation adds deployment metadata and reorders workflow permission properties.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 2575e

The reviewed changes have no identified merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowJob
  participant GithubLookup
  participant EnvironmentStore
  WorkflowJob->>GithubLookup: Resolve effective id-token permission
  WorkflowJob->>EnvironmentStore: Resolve persisted environment
  WorkflowJob->>WorkflowJob: Emit GH_CanRequestOIDCTokenFor

Loading

Suggested reviewers: d3vzer0

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 68 functions across 20 files. (18 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary objective: optimizing GitHub environment collection by using repository-reported counts to skip unnecessary collection.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 10.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 68 functions across 20 files. (18 skipped: 18 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/BED-9680-optimize-environment-collection

---

_{A rabbit hops where permissions flow
OIDC paths now clearly show
Runners sort in steady line
Counts and secrets align
Docs bloom fresh in moonlit glow}

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