docs(source-greenhouse): document key permissions, streams, and v1 deprecation

[devin-ai-integration]

Triggering Context

Run triggered by: Merged commit on master for source-greenhouse, delivered through the connectordocs automation (!connectordocs playbook macro).

Relevant context: commit 722558a / #83811 — feat(source-greenhouse): non-breaking prep for Harvest v3 migration (0.7.33 → 0.8.0).

Confidence impact: The trigger was a moderate, already-merged connector PR with clear scope (URL/pagination refactor plus new external doc URLs), so the triggering context is unambiguous — scored 4 rather than 5 because the connector change is the first step of a multi-release migration whose end state isn't merged yet.

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	5/5	Manifest-only connector; every documented endpoint, cursor field, error-handling rule, and config field was read directly out of manifest.yaml.
API Documentation Quality	5/5	Greenhouse publishes complete public docs for both the legacy Harvest v1/v2 API and Harvest v3, including auth, rate limits, and per-endpoint references.
Change Scope & Risk	3/5	~117 lines changed: the stream list became a table and three sections were added, but setup and sync-mode content is largely unchanged.
Existing Doc Maturity	3/5	The doc was ~75 lines of prose plus a long changelog: setup and stream coverage existed, but there was no troubleshooting, no config-field guidance, and no rate-limit specifics.
Connector Sensitivity	4/5	supportLevel: community with ql: 200 / sl: 100, but releaseStage: generally_available, so a doc error still reaches real users.
Triggering Context	4/5	Merged PR with clear scope; part of an in-progress migration.
Inference Ratio	4/5	Endpoints, cursors, 403 handling, check stream, and rate limits are verified; the phrasing of user-facing consequences and the expected credential change are reasoned from Greenhouse's stated plan rather than from shipped code.

Adjustments based on code comprehension

None — scored at baseline (manifest-only = 5). The documented surface is entirely declarative: stream URLs, DatetimeBasedCursor cursor fields, the per-stream HttpResponseFilter that ignores 403, check.stream_names, concurrency_level, and spec. The connector's only custom component (GreenhouseStateMigration) is not part of what this PR documents.

What I Verified vs. What I Inferred

• Verified from code (airbyte-integrations/connectors/source-greenhouse/manifest.yaml, metadata.yaml):
  • The Harvest endpoint and parent/child relationship behind each of the 36 streams, and which streams have a DatetimeBasedCursor plus its cursor field.
  • Every stream ignores HTTP 403 (action: IGNORE), so an unpermitted endpoint yields an empty stream instead of a failed sync.
  • check reads the users stream.
  • The num_workers spec field: title Number of concurrent threads, default 2, minimum 1, maximum 8, feeding concurrency_level.
  • The connector still calls /v1/... endpoints on harvest.greenhouse.io.
• Verified from API docs:
  • Harvest API key creation path (Configure > Dev Center > API Credential Management), the Can manage ALL organization's API Credentials developer permission, per-endpoint permission grants for keys created after 2017-01-18, and that key access to an endpoint is all-or-nothing.
  • v1/v2 rate limiting: the allowance is the X-RateLimit-Limit header value (example: 50) per 10-second window, with 429 + Retry-After on overage.
  • Greenhouse's deprecation notice: Harvest v1/v2 removal on 2026-08-31, and that OAuth becomes the only supported auth method afterwards.
• Inferred:
  • That the connector's credential input will change from an API key to OAuth client credentials when the v3 migration lands. This follows from Greenhouse's statement, but no Airbyte release has shipped it, so treat it as a heads-up rather than a promise.
  • The characterization of activity_feed, approvals, tags, and user_permissions as potentially slow: the fan-out (one request per parent record) is verified in the manifest; "can be slow on large accounts" is my reading of the consequence, not a measurement.
  • Guidance on when to raise or lower Number of concurrent threads — grounded in the spec description and the rate-limit math, not in benchmarks.

Areas of Concern

• The Harvest v1 deprecation section makes a forward-looking statement about credentials changing. If Airbyte plans a different migration path (for example, supporting the transition-period JWT token endpoint so the existing API key keeps working), that paragraph should be reworded or dropped.
• The stream table intentionally drops the previous per-stream links to harvestdocs.greenhouse.io/reference/get_v3-*. Those links pointed at v3 resources while the connector reads v1, and several were duplicated or wrong (Disciplines linked to the approval-flows endpoint). Harvest v3 has no equivalent for activity_feed, degrees, disciplines, or schools, so a complete per-stream link set isn't possible today. If you'd rather keep per-stream links, they should come back once the connector actually reads v3.
• The changelog date for 0.8.0 was corrected from 2026-08-11 to 2026-08-12, the merge date of commit 722558a.

---

What

Rewrites the user-facing docs for source-greenhouse so they match what the connector actually does, and adds the operational information that was missing: how to create a Harvest key with the right permissions, what each stream reads, the real rate limit, and why a stream can quietly return zero records.

Also documents that Greenhouse is removing the Harvest v1/v2 API on 2026-08-31 — the API this connector reads today — which is the context for the 0.8.0 change that triggered this run.

How

Corrections

• Replaced links to the deprecated developers.greenhouse.io/harvest.html docs with the current harvestdocs.greenhouse.io equivalents, matching the externalDocumentationUrls update in feat(source-greenhouse): non-breaking prep for Harvest v3 migration #83811.
• Fixed the 0.8.0 changelog date (2026-08-11 → 2026-08-12, the merge date).
• Removed per-stream reference links that pointed at v3 endpoints the connector doesn't call, including the Disciplines link that went to the approval-flows endpoint and several duplicates.

Additions

• Prerequisites now spell out how to create a Harvest API key, the developer permission needed to create one, per-endpoint permission grants, and the all-or-nothing nature of Harvest key access.
• Setup steps cover Number of concurrent threads, which was previously undocumented despite being user-configurable since 0.7.22.
• New Harvest v1 deprecation section.
• New Troubleshooting section for the two failure modes visible in the manifest: 403 responses silently producing empty streams, and the users-based connection check.
• Performance considerations now state the actual rate limit and how it interacts with the concurrency setting.

Restructuring

• The stream bullet list became a table of stream name, Harvest endpoint, and cursor field. Stream names now match the names users see in the UI (for example applications_interviews) instead of prose titles, and child streams are identifiable by their {...} path segments.

Review Guide

• docs/integrations/sources/greenhouse.md lines 5–17: API key prerequisites — worth checking against your own experience of the Greenhouse UI, since the path names come from Greenhouse's docs rather than a screenshot.
• Lines 40–83: stream table. Endpoints and cursor fields are transcribed from manifest.yaml; a spot-check of a few rows is the fastest way to validate it.
• Lines 85–88: the deprecation section, including the inferred credential change flagged above.
• Lines 94–97: troubleshooting entries.

User Impact

Documentation only — no connector behavior changes. Users get accurate setup prerequisites, an explanation for silently empty streams, and advance notice of the Harvest v1 removal deadline.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

---

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and third-party API documentation. Reviewers may merge, modify, or close this PR as they see fit.

Link to Devin session: https://app.devin.ai/sessions/cf14b3fbb6da49adb9db762508a1a3a9

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-d8yu8e92l-airbyte-growth.vercel.app
Latest Commit:	2ec5059

Deployed with vercel-action