Skip to content

Commit 71045a2

Browse files
mmorel-35mmorel-35
committed
Add BCR publishing automation with workflow and configuration
Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
1 parent 283f103 commit 71045a2

File tree

5 files changed

+299
-0
lines changed

5 files changed

+299
-0
lines changed

‎.bcr/README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Bazel Central Registry (BCR) Publishing for grpc-java
2+
3+
This document explains how grpc-java releases are published to the [Bazel Central Registry (BCR)](https://github.com/bazelbuild/bazel-central-registry).
4+
5+
## Overview
6+
7+
The BCR is the official registry for Bazel modules, allowing users to depend on grpc-java using Bazel's module system (bzlmod). When a new version of grpc-java is released, it is automatically published to the BCR via a GitHub Actions workflow.
8+
9+
## How It Works
10+
11+
### Automated Publishing Workflow
12+
13+
The publishing process is automated through the GitHub Actions workflow located at `.github/workflows/publish-to-bcr.yml`. This workflow:
14+
15+
1. **Triggers automatically** when a new release is published on GitHub
16+
2. **Can be manually triggered** via workflow_dispatch for re-runs or troubleshooting
17+
3. **Uses the official publish-to-bcr action** from bazel-contrib
18+
4. **Generates attestations** for release provenance and security
19+
5. **Creates a pull request** directly to the official Bazel Central Registry (https://github.com/bazelbuild/bazel-central-registry) with the new version
20+
21+
### BCR Configuration Files
22+
23+
The BCR configuration is stored in the `.bcr/` directory:
24+
25+
- **`metadata.template.json`**: Contains module metadata including homepage, maintainers, and repository information
26+
- **`source.template.json`**: Specifies how to download the source archive (uses GitHub release tags)
27+
- **`presubmit.yml`**: Defines CI tests that run in the BCR before accepting the new version
28+
29+
### Presubmit Testing
30+
31+
Before a new version is accepted into the BCR, it must pass presubmit tests defined in `.bcr/presubmit.yml`. These tests:
32+
33+
- **Build key targets** from the grpc-java module to ensure basic functionality
34+
- **Test the examples module** which demonstrates using grpc-java as a dependency
35+
- **Run on multiple platforms**: Debian, macOS, Ubuntu, Windows
36+
- **Test with multiple Bazel versions**: 7.x and 8.x
37+
38+
The examples directory serves as a test module that uses `local_path_override` to depend on the main grpc-java module, providing comprehensive integration testing.
39+
40+
## Setup and Configuration
41+
42+
### For Repository Maintainers
43+
44+
To enable BCR publishing for grpc-java, follow these steps:
45+
46+
#### 1. Create a Personal Access Token (PAT)
47+
48+
A GitHub Personal Access Token is required to create pull requests to the Bazel Central Registry.
49+
50+
**Creating a Classic PAT:**
51+
52+
1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
53+
2. Click "Generate new token (classic)"
54+
3. Give it a descriptive name like "grpc-java BCR Publishing"
55+
4. Select the following scopes:
56+
- `repo` (Full control of private repositories)
57+
- `workflow` (Update GitHub Action workflows)
58+
5. Set an appropriate expiration (consider using no expiration for automation)
59+
6. Click "Generate token" and **save the token securely**
60+
61+
**Note about Fine-grained PATs:**
62+
Fine-grained tokens are not fully supported yet because they cannot open pull requests against public repositories (see [GitHub roadmap issue #600](https://github.com/github/roadmap/issues/600)).
63+
64+
#### 2. Configure Repository Secrets
65+
66+
1. Go to the grpc-java repository Settings → Secrets and variables → Actions
67+
2. Click "New repository secret"
68+
3. Name: `BCR_PUBLISH_TOKEN`
69+
4. Value: Paste the PAT you created
70+
5. Click "Add secret"
71+
72+
#### 3. Verify Workflow Permissions
73+
74+
Ensure the workflow has the necessary permissions in the repository settings:
75+
76+
- Go to Settings → Actions → General → Workflow permissions
77+
- Ensure "Read and write permissions" is selected
78+
- Ensure "Allow GitHub Actions to create and approve pull requests" is checked
79+
80+
## Publishing a New Release
81+
82+
### Automatic Publishing
83+
84+
When you create a new release on GitHub:
85+
86+
1. Go to the grpc-java repository
87+
2. Create a new release with a tag (e.g., `v1.76.0`)
88+
3. The `publish-to-bcr.yml` workflow will automatically trigger
89+
4. Monitor the workflow run in the Actions tab
90+
5. If successful, a PR will be created in the BCR repository
91+
92+
### Manual Publishing
93+
94+
If you need to manually trigger the publishing workflow:
95+
96+
1. Go to Actions → Publish to BCR
97+
2. Click "Run workflow"
98+
3. Enter the tag name (e.g., `v1.76.0`)
99+
4. Click "Run workflow"
100+
101+
### Monitoring the Workflow
102+
103+
1. Go to the Actions tab in the grpc-java repository
104+
2. Look for the "Publish to BCR" workflow run
105+
3. Check the logs for any errors or issues
106+
4. If successful, you'll see a link to the created BCR pull request
107+
108+
## BCR Pull Request Review
109+
110+
After the workflow creates a PR in the BCR:
111+
112+
1. The PR will be automatically assigned to the module maintainers
113+
2. BCR CI will run presubmit tests to validate the new version
114+
3. Maintainers should review and approve the PR
115+
4. Once approved and tests pass, the BCR team will merge the PR
116+
5. The new version becomes available in the BCR
117+
118+
## Troubleshooting
119+
120+
### Common Issues
121+
122+
**Workflow fails with authentication error:**
123+
- Verify the `BCR_PUBLISH_TOKEN` secret is correctly set
124+
- Ensure the PAT has not expired
125+
- Check that the PAT has the required `repo` and `workflow` scopes
126+
127+
**Presubmit tests fail in BCR:**
128+
- Review the test logs in the BCR PR
129+
- Ensure the MODULE.bazel file is correctly formatted
130+
- Verify all dependencies are available in BCR
131+
- Test locally using the BCR's local testing instructions
132+
133+
**PR creation fails:**
134+
- Verify the registry fork exists and is accessible
135+
- Ensure the PAT has permissions for the fork repository
136+
- Check that the workflow has correct permissions
137+
138+
**Version already exists:**
139+
- BCR is add-only; you cannot replace existing versions
140+
- If a fix is needed, it should be fixed upstream and a new version submitted
141+
- If the fix is only in BCR patches (nothing to fix upstream), use the `.bcr.N` suffix format (e.g., `1.75.0.bcr.1`)
142+
143+
### Getting Help
144+
145+
- Check the [BCR documentation](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md)
146+
- Review the [publish-to-bcr documentation](https://github.com/bazel-contrib/publish-to-bcr)
147+
- Contact BCR maintainers at bcr-maintainers@bazel.build
148+
- File issues in the appropriate repository
149+
150+
## Maintainers
151+
152+
The following people are listed as maintainers for grpc-java in the BCR and will be notified of new PRs:
153+
154+
- Eric Anderson (@ejona86)
155+
- Agra Bimantara (@AgraVator)
156+
- Kannan Rajah (@kannanjgithub)
157+
- Shiva (@shivaspeaks)
158+
159+
Maintainers have approval rights for BCR PRs related to grpc-java, even without direct write access to the BCR repository.
160+
161+
## Patches
162+
163+
The BCR may include patches to the grpc-java module to ensure compatibility with the rest of the BCR ecosystem. These patches are typically applied by BCR maintainers and may include:
164+
165+
- Updating dependency versions to use BCR-compatible versions
166+
- Adding missing dependencies required for Bazel module builds
167+
- Adjusting build configurations for BCR compatibility
168+
169+
**Note:** If you need to include custom patches with your release, you can add them to the `.bcr/patches/` directory in the grpc-java repository. All patches must:
170+
- Have the `.patch` extension
171+
- Be in the `-p1` format (apply from the repository root)
172+
- Be listed in the BCR entry's `source.json` file (automatically handled by the publish-to-bcr workflow)
173+
174+
The publish-to-bcr workflow will automatically include any patches found in `.bcr/patches/` when creating the BCR entry.
175+
176+
## Module Structure
177+
178+
grpc-java is published as a single module to the BCR:
179+
180+
- **Main module**: The root `MODULE.bazel` defines the grpc-java module
181+
- **Test module**: The `examples/` directory serves as a test module during presubmit
182+
183+
If additional modules need to be published from this repository in the future, they can be configured using the `moduleRoots` field in `.bcr/config.yml`.
184+
185+
## References
186+
187+
- [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
188+
- [BCR Contribution Guidelines](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md)
189+
- [publish-to-bcr GitHub Action](https://github.com/bazel-contrib/publish-to-bcr)
190+
- [Bzlmod User Guide](https://bazel.build/docs/bzlmod)
191+
- [grpc-java in BCR](https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/grpc-java)
192+
193+
## License
194+
195+
This documentation and the BCR configuration files are part of grpc-java and are subject to the same Apache 2.0 license.

‎.bcr/metadata.template.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"homepage": "https://github.com/grpc/grpc-java",
3+
"maintainers": [
4+
{
5+
"name": "Eric Anderson",
6+
"email": "ejona@google.com",
7+
"github": "ejona86",
8+
"github_user_id": 2811396
9+
},
10+
{
11+
"name": "Agra Bimantara",
12+
"github": "AgraVator",
13+
"github_user_id": 81427947
14+
},
15+
{
16+
"name": "Kannan Rajah",
17+
"github": "kannanjgithub",
18+
"github_user_id": 29600796
19+
},
20+
{
21+
"name": "Shiva",
22+
"github": "shivaspeaks",
23+
"github_user_id": 56782215
24+
}
25+
],
26+
"repository": [
27+
"github:grpc/grpc-java"
28+
],
29+
"versions": [],
30+
"yanked_versions": {}
31+
}

‎.bcr/presubmit.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# BCR presubmit configuration for grpc-java
2+
# Tests the main module and the examples test module
3+
4+
# Test the main grpc-java module
5+
matrix:
6+
platform: ["debian10", "macos", "ubuntu2004", "windows"]
7+
bazel: ["7.x", "8.x"]
8+
tasks:
9+
verify_targets:
10+
platform: ${{ platform }}
11+
bazel: ${{ bazel }}
12+
build_targets:
13+
- '@grpc-java//:java_grpc_library__external_repo_test'
14+
15+
# Test the examples module which uses grpc-java as a dependency
16+
bcr_test_module:
17+
module_path: "examples"
18+
matrix:
19+
platform: ["debian10", "macos", "ubuntu2004", "windows"]
20+
bazel: ["7.x", "8.x"]
21+
tasks:
22+
run_test_module:
23+
name: "Run examples test module"
24+
platform: ${{ platform }}
25+
bazel: ${{ bazel }}
26+
build_targets:
27+
- '//src/main/java/io/grpc/examples/helloworld:hello-world-client'
28+
- '//src/main/java/io/grpc/examples/helloworld:hello-world-server'

‎.bcr/source.template.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"integrity": "",
3+
"strip_prefix": "grpc-java-{VERSION}",
4+
"url": "https://github.com/grpc/grpc-java/archive/refs/tags/v{VERSION}.tar.gz"
5+
}

‎.github/workflows/publish-to-bcr.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Publish to BCR
2+
3+
# This workflow publishes new releases to the Bazel Central Registry (BCR)
4+
# It is triggered automatically when a new release is created
5+
6+
on:
7+
# Automatically run when a release is published
8+
release:
9+
types: [published]
10+
11+
# Allow manual triggering for re-runs or troubleshooting
12+
workflow_dispatch:
13+
inputs:
14+
tag_name:
15+
description: 'Tag name to publish (e.g., v1.75.0)'
16+
required: true
17+
type: string
18+
19+
jobs:
20+
publish:
21+
name: Publish to Bazel Central Registry
22+
# Use the reusable workflow from publish-to-bcr
23+
uses: bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@v6
24+
with:
25+
tag_name: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.tag_name }}
26+
# Repository to submit the PR to (using official BCR)
27+
# You can also use a fork by specifying: your-org/bazel-central-registry
28+
registry_fork: bazelbuild/bazel-central-registry
29+
# Generate attestations for provenance
30+
attest: true
31+
# Required permissions for the workflow
32+
permissions:
33+
contents: write
34+
# Required for generating attestations
35+
id-token: write
36+
attestations: write
37+
secrets:
38+
# Personal Access Token with 'repo' and 'workflow' permissions
39+
# Must be stored as a repository secret named BCR_PUBLISH_TOKEN
40+
publish_token: ${{ secrets.BCR_PUBLISH_TOKEN }}

0 commit comments

Comments
 (0)