{"id":29605495,"url":"https://github.com/bufbuild/buf-gradle-plugin","last_synced_at":"2026-01-29T16:00:47.459Z","repository":{"id":38448456,"uuid":"291329569","full_name":"bufbuild/buf-gradle-plugin","owner":"bufbuild","description":"Gradle plugin for the Buf CLI","archived":false,"fork":false,"pushed_at":"2026-01-26T23:50:25.000Z","size":978,"stargazers_count":56,"open_issues_count":13,"forks_count":13,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-01-27T07:19:51.096Z","etag":null,"topics":["buf","gradle","gradle-plugin","java","kotlin","protobuf","protobuf-gradle-plugin","protobuf-schema","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bufbuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-08-29T18:46:25.000Z","updated_at":"2026-01-26T23:49:41.000Z","dependencies_parsed_at":"2025-12-03T00:10:16.072Z","dependency_job_id":null,"html_url":"https://github.com/bufbuild/buf-gradle-plugin","commit_stats":null,"previous_names":["andrewparmet/buf-gradle-plugin"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/bufbuild/buf-gradle-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fbuf-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fbuf-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fbuf-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fbuf-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bufbuild","download_url":"https://codeload.github.com/bufbuild/buf-gradle-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fbuf-gradle-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28880824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buf","gradle","gradle-plugin","java","kotlin","protobuf","protobuf-gradle-plugin","protobuf-schema","protocol-buffers"],"created_at":"2025-07-20T16:05:54.918Z","updated_at":"2026-01-29T16:00:47.453Z","avatar_url":"https://github.com/bufbuild.png","language":"Kotlin","readme":"# buf-gradle-plugin\n\n[![Build](https://github.com/bufbuild/buf-gradle-plugin/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/bufbuild/buf-gradle-plugin/actions/workflows/ci.yaml)\n[![Maven Central](https://img.shields.io/badge/dynamic/xml?color=orange\u0026label=maven-central\u0026prefix=v\u0026query=%2F%2Fmetadata%2Fversioning%2Flatest\u0026url=https%3A%2F%2Frepo1.maven.org%2Fmaven2%2Fbuild%2Fbuf%2Fbuf-gradle-plugin%2Fmaven-metadata.xml)](https://search.maven.org/artifact/build.buf/buf-gradle-plugin)\n[![Gradle Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/build/buf/buf-gradle-plugin/maven-metadata.xml.svg?label=gradle-portal\u0026color=yellowgreen)](https://plugins.gradle.org/plugin/build.buf)\n\nThis project provides support for integrating [Buf][buf] with Gradle. It also enables integration with the [Protobuf Gradle plugin][protobuf-gradle-plugin] (Note: the `buf-gradle-plugin` is compatible with `protobuf-gradle-plugin` versions \u003e= 0.9.2).\n\nThis plugin supports straightforward usage of `buf lint`, `buf format`, and `buf generate`, and a self-contained integration between `buf build` and `buf breaking`.\n\n## Usage\n\nThis plugin assumes that Buf is configured for the project root with a configured `buf.yaml`, and instructions for setting up a Buf workspace can be found in the [Buf docs][buf-docs].\n\nThe plugin can also be used without specifying a `buf.yaml`, in which case the plugin will scan all top-level directories for Protobuf sources.\n\nIf the project includes the `protobuf-gradle-plugin`, this plugin will use an implicit Buf workspace that includes the following:\n- All specified Protobuf source directories\n- The `include` dependencies that the `protobuf-gradle-plugin` extracts into `$buildDir/extracted-include-protos`\n- The dependencies that the `protobuf-gradle-plugin` has been told to generate which are extracted into `$buildDir/extracted-protos`\n\nThis plugin does not support usage of both a Buf workspace and the `protobuf-gradle-plugin` because dependency resolution would be complicated and error-prone.\n\nApply the plugin:\n\n``` kotlin\nplugins {\n    id(\"build.buf\") version \"\u003cversion\u003e\"\n}\n```\n\nor\n\n``` kotlin\nbuildscript {\n    dependencies {\n        classpath(\"build.buf:buf-gradle-plugin:\u003cversion\u003e\")\n    }\n}\n\napply(plugin = \"build.buf\")\n```\n\nWhen applied, the plugin creates the following tasks:\n- `bufFormatApply` applies [`buf format`](https://buf.build/docs/format/style/)\n- `bufFormatCheck` validates [`buf format`](https://buf.build/docs/format/style/)\n- `bufLint` validates [`buf lint`](https://buf.build/docs/breaking/overview/)\n- `bufBuild` builds an image with [`buf build`](https://buf.build/docs/reference/cli/buf/build)\n- `bufBreaking` checks Protobuf schemas against a previous version for backwards-incompatible changes through [`buf breaking`](https://buf.build/docs/breaking/overview/)\n- `bufGenerate` generates Protobuf code with [`buf generate`](https://buf.build/docs/generate/overview/)\n\n### Gradle Compatibility\n\nThis plugin requires **Gradle 8 or higher**.\n\n### Examples\n\nEach [integration test](src/test/resources) in this project is an example usage.\n\n## Configuration\n\nFor a basic Buf project or one that uses the `protobuf-gradle-plugin`, you can create a Buf configuration file in the project directory:\n\n``` yaml\n# buf.yaml\n\nversion: v2\nlint:\n  ignore:\n    - path/to/dir/to/ignore\n  use:\n    - DEFAULT\n```\n\nAs an alternative to a `buf.yaml` file in the project directory, you can specify the location of a `buf.yaml` by configuring the extension:\n\n``` kotlin\nbuf {\n    configFileLocation = rootProject.file(\"buf.yaml\")\n}\n```\n\nOr you can share a Buf configuration across projects and specify it via the dedicated `buf` configuration:\n\n``` kotlin\ndependencies {\n    buf(\"build.buf:shared-buf-configuration:0.1.0\")\n}\n```\n\nAs an example, here's the setup for a `shared-buf-configuration` project:\n\n```\nshared-buf-configuration % tree\n.\n├── build.gradle.kts\n└── buf.yaml\n```\n\n``` kotlin\n// build.gradle.kts\n\nplugins {\n    `maven-publish`\n}\n\npublishing {\n    publications {\n        create\u003cMavenPublication\u003e(\"bufconfig\") {\n            groupId = \"build.buf\"\n            artifactId = \"shared-buf-configuration\"\n            version = \"0.1.0\"\n            artifact(file(\"buf.yaml\"))\n        }\n    }\n}\n```\n\nProjects with Buf workspaces must configure their workspaces as described in the Buf documentation; no configuration for linting will be overrideable. A `buf.yaml` in the project root or specified in the extension will be used for breakage checks only.\n\n### Dependencies\n\nIf your `buf.yaml` declares any dependencies using the `deps` key, you must run `buf mod update` to create a `buf.lock` file manually. The `buf-gradle-plugin` does not (yet) support creating the dependency lock file.\n\n### `bufGenerate`\n\n`bufGenerate` is configured as described in the Buf docs. Create a `buf.gen.yaml` in the project root and `bufGenerate` will generate code in the project's build directory at `\"$buildDir/bufbuild/generated/\u003cout path from buf.gen.yaml\u003e\"`.\n\nAn example, for Java code generation using the remote plugin:\n\n``` yaml\nversion: v2\nplugins:\n  - plugin: buf.build/protocolbuffers/java:\u003cversion\u003e\n    out: java\n```\n\nIf you want to use generated code in your build, you must add the generated code as a source directory and configure a task dependency to ensure code is generated before compilation:\n\n``` kotlin\n// build.gradle.kts\n\nimport build.buf.gradle.GENERATED_DIR\n\nplugins {\n    `java`\n    id(\"build.buf\") version \"\u003cversion\u003e\"\n}\n\n// Add a task dependency for compilation\ntasks.named(\"compileJava\").configure { dependsOn(\"bufGenerate\") }\n\n// Add the generated code to the main source set\nsourceSets[\"main\"].java { srcDir(\"$buildDir/bufbuild/$GENERATED_DIR/java\") }\n\n// Configure dependencies for protobuf-java:\nrepositories { mavenCentral() }\n\ndependencies {\n    implementation(\"com.google.protobuf:protobuf-java:\u003cprotobuf version\u003e\")\n}\n```\n\n#### Generating dependencies\n\nIf you'd like to generate code for your dependencies, configure the `bufGenerate` task:\n\n``` kotlin\n// build.gradle.kts\n\nbuf {\n    generate {\n        includeImports = true\n    }\n}\n```\n\nEnsure you have an up-to-date `buf.lock` file generated by `buf mod update` or this generation will fail.\n\n\n#### Further generation configuration\n\nBy default, `bufGenerate` will read the `buf.gen.yaml` template file from the project root directory. You can override the location of the template file:\n\n``` kotlin\n// build.gradle.kts\n\nbuf {\n    generate {\n        templateFileLocation = rootProject.file(\"subdir/buf.gen.yaml\")\n    }\n}\n```\n\n### `bufFormatApply` and `bufFormatCheck`\n\n`bufFormatApply` is run manually and has no configuration.\n\n`bufFormatCheck` is run automatically during the `check` task if `enforceFormat` is enabled. It has no other configuration.\n\n```kotlin\nbuf {\n    enforceFormat = true // True by default\n}\n```\n\n### `bufLint`\n\n`bufLint` is configured by creating `buf.yaml` in basic projects or projects using the `protobuf-gradle-plugin`. It is run automatically during the `check` task. Specification of `buf.yaml` is not supported for projects using a workspace.\n\n### `bufBuild`\n\n`bufBuild` is configured with the `build` closure:\n\n```kotlin\nbuf {\n    build {\n        imageFormat = ImageFormat.JSON // JSON by default\n        compressionFormat = CompressionFormat.GZ // null by default (no compression)\n    }\n}\n```\n\nAvailable image formats are:\n\n- `binpb`\n- `bin`\n- `json`\n- `txtpb`\n\nAvailable compression formats are:\n\n- `gz`\n- `zst`\n\nThe file is built in the `bufbuild` directory in the project's build directory and has the name `image` followed by\nthe image format and optionally the compression format, e.g. `build/bufbuild/image.bin.zst`.\n\n### `bufBreaking`\n\n`bufBreaking` is more complicated since it requires a previous version of the Protobuf schema to validate the current version. Buf's built-in git integration isn't quite enough since it requires a buildable Protobuf source set, and the `protobuf-gradle-plugin`'s extraction step typically targets the project build directory which is ephemeral and is not committed.\n\nThis plugin uses `buf build` to create an image from the current Protobuf schema and publishes it as a Maven publication. In subsequent builds of the project, the plugin will resolve the previously published schema image and run `buf breaking` against the current schema with the image as its reference.\n\n#### Checking against the latest published version\n\nEnable `checkSchemaAgainstLatestRelease` and the plugin will resolve the previously published Maven artifact as its input for validation.\n\nFor example, first publish the project with `publishSchema` enabled:\n\n``` kotlin\nbuf {\n    publishSchema = true\n}\n```\n\nThen configure the plugin to check the schema:\n\n``` kotlin\nbuf {\n    // Continue to publish the schema\n    publishSchema = true\n\n    checkSchemaAgainstLatestRelease = true\n}\n```\n\nThe plugin will run Buf to validate the project's current schema:\n\n```\n\u003e Task :bufBreaking FAILED\nsrc/main/proto/buf/service/test/test.proto:9:1:Previously present field \"1\" with name \"test_content\" on message \"TestMessage\" was deleted.\n```\n\n#### Checking against a static version\n\nIf for some reason you do not want to dynamically check against the latest published version of your schema, you can specify a constant version with `previousVersion`:\n\n``` kotlin\nbuf {\n    // Continue to publish the schema\n    publishSchema = true\n\n    // Will always check against version 0.1.0\n    previousVersion = \"0.1.0\"\n}\n```\n\n#### Artifact details\n\nBy default, the published image artifact will infer its details from an existing Maven publication if one exists. If one doesn't exist, you have more than one, or you'd like to specify the details yourself, you can configure them:\n\n``` kotlin\nbuf {\n    publishSchema = true\n\n    imageArtifact {\n        groupId = rootProject.group.toString()\n        artifactId = \"custom-artifact-id\"\n        version = rootProject.version.toString()\n    }\n}\n```\n\n## Additional configuration\n\nThe version of Buf used can be configured using the `toolVersion` property on the extension:\n\n``` kotlin\nbuf {\n    toolVersion = \u003cversion\u003e\n}\n```\n\n## Contributing\n\nWe'd love your help making this plugin better!\n\nExtensive instructions for building the plugin locally,\nrunning tests, and contributing to the repository are available in our\n[`CONTRIBUTING.md` guide](./.github/CONTRIBUTING.md).\n\n## Ecosystem\n\n* [connect-kotlin]: Kotlin clients for idiomatic gRPC \u0026 Connect RPC\n* [connect-es]: Type-safe APIs with Protobuf and TypeScript.\n* [connect-go]: Service handlers and clients for GoLang\n* [Buf Studio][buf-studio]: Web UI for ad-hoc RPCs\n\n## Status\n\nThis project is in beta, and we may make a few changes as we gather feedback\nfrom early adopters. Join us on [Slack][slack]!\n\n## Legal\n\nOffered under the [Apache 2 license][license].\n\n[buf]: https://buf.build/\n[buf-docs]: https://buf.build/docs/tutorials/getting-started-with-buf-cli/\n[buf-studio]: https://buf.build/studio\n[connect-kotlin]: https://github.com/connectrpc/connect-kotlin\n[connect-go]: https://github.com/connectrpc/connect-go\n[connect-es]: https://github.com/connectrpc/connect-es\n[license]: https://github.com/connectrpc/connect-go/blob/main/LICENSE\n[protobuf-gradle-plugin]: https://github.com/google/protobuf-gradle-plugin\n[slack]: https://buf.build/links/slack\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fbuf-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbufbuild%2Fbuf-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fbuf-gradle-plugin/lists"}