README.md

buf-push-action

This Action enables you to push Buf modules to the Buf Schema Registry (BSR) Pushed modules are created with the Git commit SHA as the module tag.

buf-push-action is frequently used alongside other Buf Actions, such as buf-breaking-action and buf-lint-action.

Usage

Here's an example usage of buf-push-action:

on: pull_request # Apply to all pull requests
jobs:
  push-module:
    # Run `git checkout`
    - uses: actions/checkout@v2
    # Install the `buf` CLI
    - uses: bufbuild/buf-setup-action@v1
    # Push module to the BSR
    - uses: bufbuild/buf-push-action@v1
      with:
        buf_token: ${{ secrets.BUF_TOKEN }}
        enable_draft: true

With this configuration, the buf CLI pushes the configured module to the BSR using a Buf API token to authenticate with the Buf Schema Registry (BSR), upon a pull request opened, synchronize, or reopened, and will push as a draft when the triggering branch is not main.

For instructions on creating a BSR API token, see our official docs. Once you've created a an API token, you need to create an encrypted Github Secret for it. In this example, the API token is set to the BUF_TOKEN secret.

Prerequisites

For buf-push-action to run, you need to install the buf CLI in the GitHub Actions Runner first. We recommend using buf-setup-action to install it (as in the example above).

Configuration

Parameter	Description	Required	Default
buf_token	The Buf authentication token used for private Buf inputs	✅	${{github.token}}
input	The path of the input you want to push to BSR as a module		.
enable_draft	Enable to push the BSR commit as draft when the git branch that triggering the workflow is not main

These parameters are derived from action.yml.

Common tasks

Run against input in sub-directory

Some repositories are structured so that their buf.yaml configuration file is defined in a sub-directory alongside their Protobuf sources, such as a proto directory. Here's an example:

$ tree
.
└── proto
    ├── acme
    │   └── weather
    │       └── v1
    │           └── weather.proto
    └── buf.yaml

In that case, you can target the proto sub-directory by setting input to proto:

steps:
  # Run `git checkout`
  - uses: actions/checkout@v2
  # Install the `buf` CLI
  - uses: bufbuild/buf-setup-action@v1
  # Push only the Input in `proto` to the BSR
  - uses: bufbuild/buf-push-action@v1
    with:
      input: proto
      buf_token: ${{ secrets.BUF_TOKEN }}

Validate before push

buf-push-action is typically used alongside other buf Actions, such as buf-breaking-action and buf-lint-action. A common use case is to "validate" a Buf module before pushing it to the BSR by ensuring that it passes both lint and breaking change checks, as in this example:

on: # Apply to all pushes to `main`
  push:
    branches:
      - main
jobs:
  validate-and-push-protos:
    runs-on: ubuntu-latest
    steps:
      # Run `git checkout`
      - uses: actions/checkout@v2
      # Install the `buf` CLI
      - uses: bufbuild/buf-setup-action@v1
      # Run a lint check on Protobuf sources
      - uses: bufbuild/buf-lint-action@v1
      # Run breaking change detection for Protobuf sources against the current `main` branch
      - uses: bufbuild/buf-breaking-action@v1
        with:
          against: https://github.com/acme/weather.git#branch=main,ref=HEAD~1,subdir=proto
      # Push the validated module to the BSR
      - uses: bufbuild/buf-push-action@v1
        with:
          buf_token: ${{ secrets.BUF_TOKEN }}