chore(workflows): Consolidate Vale linting into Reviewdog workflow

[devin-ai-integration]

What

Consolidates the Vale linting job from PR #65973 into the existing Reviewdog workflow. This adds Vale as a second documentation linting job alongside MarkdownLint, both using the same reviewdog reporter for consistency.

Related to #65973

How

Workflow Changes (.github/workflows/reviewdog.yml):

• Updated workflow comments to reflect that both MarkdownLint and Vale run on docs
• Added a new vale job that runs after the markdownlint job
• Configured Vale to use github-pr-review reporter (matching MarkdownLint's configuration)
• Uses filter_mode: added to only lint newly added content
• Uses fail_on_error: false to keep Vale checks non-blocking

Vale Configuration Changes (docusaurus/vale.ini):

• Changed MinAlertLevel from suggestion to warning
• This scopes Vale to only report warnings and errors, excluding suggestions

Review guide

1. .github/workflows/reviewdog.yml - Review the Vale job configuration:

   • Verify the errata-ai/vale-action parameters are correct
   • Confirm github-pr-review is the appropriate reporter (changed from github-pr-check in the original PR Docs Vale lint on PRs #65973)
   • Check that filter_mode: added and fail_on_error: false are the desired settings

2. docusaurus/vale.ini - Review the MinAlertLevel change:

   • Confirm MinAlertLevel = warning is the desired behavior (excludes suggestions, only shows warnings and errors)
   • Note: The airbyte.punctuation = NO rule was already removed in master, so no changes needed there

User Impact

Positive:

• Documentation PRs will now receive automated Vale linting feedback alongside MarkdownLint
• Both linters use the same reporter type for consistent PR annotations
• Vale will only flag warnings and errors, reducing noise from suggestions

Neutral:

• This supersedes the separate Vale workflow from PR Docs Vale lint on PRs #65973, which can be closed once this is merged
• No impact to existing MarkdownLint checks

Can this PR be safely reverted and rolled back?

• YES 💚

This only adds a new linting job to the Reviewdog workflow. Reverting would simply remove the Vale checks without affecting the existing MarkdownLint job or any other workflows.

---

Session Details:

• Requested by: Ian Alton ([email protected])
• Link to Devin run: https://app.devin.ai/sessions/7993d1cba2464b48bbababe88bda0671

Important

Auto-merge enabled.

This PR is set to merge automatically when all requirements are met.

[devin-ai-integration]

Original prompt from [email protected]

@Devin take a look at this PR. I think this works fine, but I'd like to consolidate this job into the Reviewdog workflow. Even though this isn't a true Reviewdog workflow, it uses reviewdog under the hood so that seems most appropriate.

Create a new PR that expands Reviewdog and adds Vale as a new job after MarkDownLint.

• Update the comments to include the fact that we also run Vale on the docs.
• Name: Vale
• runs-on ubuntu-latest
• For flags, keep the same configuration, but use github-pr-review instead of github-pr-check as the reporter.
• If possible, scope it to warnings and errors, not suggestions. You may need to investigate the Vale workflow docs to see if this is supported.
• The Airbyte punctuation rule configuration is no longer needed because it's been deleted in master.
• I think the other settings can remain the same.
Thread URL: https://airbytehq-team.slack.com/archives/D08FX8EC9L0/p1760133456029459?thread_ts=1760133456.029459

[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 and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Live Tests
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

PR Slash Commands

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

• /format-fix - Fixes most formatting issues.
• /bump-version - Bumps connector versions.
  • You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
  • Leaving the changelog arg blank will auto-populate the changelog from the PR title.
• /run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
• /build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
• 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
  • /bump-bulk-cdk-version type=patch changelog='foo' - Bump the Bulk CDK's version. type can be major/minor/patch.
• 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.

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-91lwortis-airbyte-growth.vercel.app

Built with commit d088db3.
This pull request is being automatically deployed with vercel-action

[devin-ai-integration]

Good catch! I investigated the Vale action documentation and found that we can use the --minAlertLevel=warning flag in the workflow's vale_flags parameter.

I've now:

• Reverted vale.ini back to MinAlertLevel = suggestion (so local linters can see suggestions)
• Added --minAlertLevel=warning to the workflow's vale_flags parameter (so CI only reports warnings and errors)

This way, developers running Vale locally will see all suggestions, while the CI workflow will only report warnings and errors in PR reviews.

[devin-ai-integration]

Good question! I matched the version used in the existing markdownlint job above it (v4.2.2), but you're right that the original Vale workflow in PR #65973 used V5.

I've updated it to use the V5 hash (actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8) to match the original Vale workflow.

[devin-ai-integration]

Done! I've added inline comments explaining the purpose of each of the 5 Vale configuration parameters:

• vale_flags: Location of Vale's config file and min alert level for CI
• files: Folder in which to lint
• filter_mode: Only lint things that have changed
• fail_on_error: Don't fail if the linter finds issues (compliance is optional)
• reporter: Post as annotations on the Changed Files page

[ian-at-airbyte]

Great. Now that we have multiple checkouts happening, is it possible to consolidate into one checkout that all jobs can use? This seems more efficient especially if we later add new jobs.

[devin-ai-integration]

Good question! In GitHub Actions, jobs run on separate runners and don't share workspaces by default. I can think of a few approaches:

1. Use the same checkout version in both jobs (simple, consistent)

   • Update both markdownlint and vale jobs to use the same checkout action version (either v4.2.2 or V5)
   • This provides consistency without added complexity

2. Share checkout via artifacts (more complex, possibly over-engineered for this use case)

   • Create a separate checkout job that uploads the code as an artifact
   • Have both jobs depend on the checkout job and download the artifact
   • This adds complexity and might not provide significant benefit for just checking out code

3. Keep as-is (current approach)

   • Each job independently checks out the code
   • This is the standard GitHub Actions pattern for simple workflows

Which approach would you prefer? For most workflows like this, option 1 (same version) or option 3 (keep as-is) are typical. Let me know what you had in mind!

[ian-at-airbyte]

Alright this looks fine, we'll stick with using distinct checkouts on each runner. Now let's run a test. Create a new test PR and attempt to merge it back into this one. In that PR, create a new file that violates linting rules. You can populate it with the content from docs/platform/community/getting-support.md, because that file has a variety of violations that should trigger the linter. You should also mess the test file up a bit by removing blank lines around headings and lists. This should provide a long list of violations from both markdownlint and vale that shows this workflow in action.

[devin-ai-integration]

✅ Test Results: Reviewdog Workflow Validated

I've created test PR #67621 to validate the consolidated Reviewdog workflow, and it's working perfectly!

Test PR: #67621

Results:

• ✅ Both linters ran successfully
  • Docs / MarkDownLint job completed
  • Docs / Vale job completed
• ✅ Both linters reported violations (58 automated comments total)
  • MarkdownLint violations (MD022, MD032): Headings and lists should be surrounded by blank lines
  • Vale style violations: Capitalization, exclamation points, spelling, units formatting, AM/PM usage
• ✅ CI checks passed (as expected with fail_on_error: false)
• ✅ Violations appear as PR review annotations on the Files Changed page

The test file intentionally violated formatting rules by removing blank lines around headings and lists, and included content that triggers Vale style violations. Both linters caught and reported the issues correctly.

The consolidated Reviewdog workflow is ready for use! 🎉

[ian-at-airbyte]

Great. Last step is to update contribution documentation. https://docs.airbyte.com/platform/next/contributing-to-airbyte/writing-docs#linting

• Update the current and historical platform versions of this doc.
• In the note "Vale and MarkDownLint are newly implemented. They might still generate false positives or false negatives. Currently, MarkDownLint is the only one of the two that runs on pull requests, and compliance isn't mandatory. This may change in the future. For now, just do your best to comply with the linters' recommendations as you see them." Specifically, remove this part: "Currently, MarkDownLint is the only one of the two that runs on pull requests, and compliance isn't mandatory. This may change in the future."
• Create a new subsection that explains how the linters work in CI, with a brief explanation, based on the work you did here. Recommend that authors run them locally as explained in the other two subsections, but explain this is optional and CI will capture warnings and errors. Suggestions are only available when running locally.