setup-google-api-linter

A GitHub Action that installs and runs the Google AIP api-linter against your Protocol Buffer files. It downloads a pinned (or the latest) linter release, lints your protos, and surfaces the results as inline annotations, a job-summary table, action outputs, and an optional report file.

The table of contents below maps the whole document. Each entry is a link to the matching section, so you can jump straight to what you need instead of scrolling: skim Features and Quick start to get running, use Inputs and Outputs as the configuration reference, and see Contributing and License for project and legal details.

• How it works
• Features
• Quick start
• Inputs
• Outputs
• How results are surfaced
• Supported runners
• Why the bundle is committed
• Versioning
• Contributing
• License

How it works

Features

• Installs any published api-linter version, or resolves latest.
• Caches the binary across runs via the Actions tool cache.
• Inline pull-request annotations for every rule violation.
• Job-summary table with a link to each AIP rule.
• Optional machine-readable report (json, yaml, github, summary).
• Supports config files, import paths, rule toggles and descriptor sets.
• Written entirely in documented TypeScript.

Quick start

name: API lint
on: [pull_request]
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: the-protobuf-project/setup-google-api-linter@v1
        with:
          paths: proto/**/*.proto

By default the action lints **/*.proto, installs the latest linter, annotates each problem, writes a job summary, and fails the job if any problem is found.

Inputs

Outputs

How results are surfaced

• Annotations — each problem becomes an inline error annotation on the relevant proto line (disable with annotate: false).
• Job summary — a table of file, line, rule and message, with each rule linking to its page on linter.aip.dev (disable with job-summary: false).
• Report file — set output-path to write the full report in output-format for archiving or downstream tooling.
• Outputs — read problem-count, version and results-path in later steps.

See docs/examples.md for config files, import paths, rule overrides, descriptor sets, artifact uploads and more.

Resolving Buf dependencies

If your protos import types managed by Buf — for example google/api/* pulled from the Buf Schema Registry via buf.yaml deps — set buf: true. The action runs buf export to materialise those dependencies onto disk and adds them to api-linter’s import paths, so imports resolve instead of failing. buf is used from PATH when present, otherwise it is installed automatically — or point buf-path at your own buf executable. To use a buf.yaml that lives outside the input directory, set buf-config to its path.

- uses: the-protobuf-project/setup-google-api-linter@v1
  with:
    buf: true
    working-directory: proto # directory containing buf.yaml
    paths: "**/*.proto"

A complete, AIP-compliant example module lives in examples/buf; it is exercised end-to-end by the golden test.

Supported runners

api-linter publishes binaries for these platforms, all of which this action supports:

Linux arm64 is not published upstream and is therefore unsupported; the action fails with a clear message on unsupported hosts.

Why the bundle is committed

GitHub runs a JavaScript action by executing its compiled entry point directly from the repository at the ref you pin — it does not run bun install or bun run build for you. The bundled dist/index.js (produced by bun run build) is therefore committed to the repository, and CI fails if it drifts from src/. Rebuild and commit dist/ after any change under src/.

Versioning

• Reference a released major tag (@v1) for stability, or a full commit SHA for maximum pinning.
• No auto-fix — api-linter is a linter, not a formatter, so it does not rewrite protos. This action surfaces problems (including any suggestion fields) and can persist a report; applying changes is left to you.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow, coding standards, and how to run bun run all before opening a pull request. In short: this project uses Bun, all code is documented TypeScript, and every file stays under 200 lines.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text and NOTICE for attribution.

api-linter is a separate Google project, also under Apache-2.0; this action installs and invokes it but does not redistribute it.