Skip to content

Commit 5c2aaae

Browse files
mmorel-35mmorel-35
committed
Add automated BCR publication via publish-to-bcr workflow
Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
1 parent 805682e commit 5c2aaae

File tree

6 files changed

+214
-0
lines changed

6 files changed

+214
-0
lines changed

‎.bcr/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Bazel Central Registry (BCR) Publication
2+
3+
This directory contains configuration files for automated publication of s2geometry to the [Bazel Central Registry (BCR)](https://github.com/bazelbuild/bazel-central-registry).
4+
5+
## Overview
6+
7+
The s2geometry project uses [publish-to-bcr](https://github.com/bazel-contrib/publish-to-bcr) to automatically publish new releases to the Bazel Central Registry. When a new release is created, the GitHub Actions workflow will:
8+
9+
1. Extract release information from the git tag
10+
2. Generate a BCR entry using the template files in this directory
11+
3. Create a pull request to the Bazel Central Registry
12+
13+
## Files in this Directory
14+
15+
### config.yml
16+
Configuration specific to s2geometry:
17+
- `moduleRoots: ["src"]` - Indicates that MODULE.bazel is in the src/ directory
18+
19+
### src/metadata.template.json
20+
Contains the project metadata including:
21+
- Homepage URL
22+
- Maintainer information (Vincent Tsao and Jesse Rosenstock)
23+
- Repository location
24+
- Version tracking (automatically updated)
25+
26+
### src/source.template.json
27+
Defines how to download the source archive:
28+
- `url`: GitHub release archive URL pattern
29+
- `strip_prefix`: Since s2geometry's MODULE.bazel is in the `src/` directory, we strip to `{REPO}-{VERSION}/src`
30+
- `integrity`: Automatically computed by the workflow
31+
32+
### src/presubmit.yml
33+
Defines the BCR presubmit tests that will run when the PR is opened:
34+
- Build targets to verify
35+
- Test targets to run
36+
- Platform matrix (Linux, macOS, macOS ARM64)
37+
- Bazel version matrix (7.x, 8.x, rolling)
38+
39+
## Setup for Maintainers
40+
41+
### Prerequisites
42+
43+
To use the automated BCR publication workflow, a maintainer must:
44+
45+
1. **Create a Personal Access Token (PAT)**
46+
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
47+
- Click "Generate new token (classic)"
48+
- Give it a descriptive name like "BCR Publication for s2geometry"
49+
- Select the following permissions:
50+
- ✅ `repo` (Full control of private repositories)
51+
- ✅ `workflow` (Update GitHub Action workflows)
52+
- Set an appropriate expiration date (consider using no expiration for automation, or set calendar reminders to regenerate)
53+
- Click "Generate token" and **copy the token immediately** (you won't be able to see it again)
54+
55+
2. **Add the PAT as a Repository Secret**
56+
- Go to the s2geometry repository settings
57+
- Navigate to Secrets and variables → Actions
58+
- Click "New repository secret"
59+
- Name: `BCR_PUBLISH_TOKEN`
60+
- Value: Paste the PAT you created
61+
- Click "Add secret"
62+
63+
Note: The PAT owner must have a fork of the Bazel Central Registry. The workflow will automatically use the fork associated with the PAT owner's account.
64+
65+
## How to Publish a New Release
66+
67+
Once the setup is complete, publishing to BCR is automatic:
68+
69+
1. **Create a Release on GitHub**
70+
- Go to the repository's "Releases" page
71+
- Click "Draft a new release"
72+
- Create a new tag following the existing pattern (e.g., `v0.13.0`)
73+
- Fill in release notes
74+
- Click "Publish release"
75+
76+
2. **Workflow Triggers Automatically**
77+
- The `publish-to-bcr.yml` workflow will trigger automatically
78+
- Monitor the workflow run in the Actions tab
79+
80+
3. **Review the BCR Pull Request**
81+
- Once the workflow completes, a pull request will be opened in the Bazel Central Registry
82+
- The BCR maintainers will review and merge it
83+
- You can view the PR by checking the workflow logs for the PR URL
84+
85+
## Manual Triggering
86+
87+
If needed, you can manually trigger the publication workflow:
88+
89+
1. Go to Actions → "Publish to BCR"
90+
2. Click "Run workflow"
91+
3. Enter the tag name (e.g., `v0.13.0`)
92+
4. Click "Run workflow"
93+
94+
## Troubleshooting
95+
96+
### Workflow Fails with "Authentication Error"
97+
- The PAT may have expired or lacks necessary permissions
98+
- Generate a new PAT with `repo` and `workflow` permissions
99+
- Update the `BCR_PUBLISH_TOKEN` secret
100+
101+
### Workflow Fails with "Fork Not Found"
102+
- Ensure the PAT owner has a fork of bazelbuild/bazel-central-registry
103+
- Verify the fork is accessible by the PAT owner
104+
105+
### BCR PR Fails Presubmit Tests
106+
- Check the presubmit.yml configuration in this directory
107+
- Ensure the build and test targets are correct
108+
- The BCR presubmit will show specific error messages
109+
110+
### Module Not Found or Wrong Path
111+
- This usually indicates an issue with `moduleRoots` in config.yml or `strip_prefix` in src/source.template.json
112+
- For s2geometry, MODULE.bazel is in `src/`, so:
113+
- `config.yml` should have `moduleRoots: ["src"]`
114+
- `src/source.template.json` should have `strip_prefix: "{REPO}-{VERSION}/src"`
115+
- Template files are in `.bcr/src/` to match the module structure
116+
117+
## Security Notes
118+
119+
- The PAT should be treated as a sensitive credential
120+
- Only repository administrators should have access to repository secrets
121+
- Consider using a dedicated bot account for BCR publications
122+
- Regularly rotate the PAT (set expiration dates and calendar reminders)
123+
- The PAT only needs write access to your fork of the BCR, not to the main repository
124+
125+
## References
126+
127+
- [publish-to-bcr Documentation](https://github.com/bazel-contrib/publish-to-bcr)
128+
- [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
129+
- [Bzlmod User Guide](https://bazel.build/docs/bzlmod)
130+
- [s2geometry in BCR](https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/s2geometry)

‎.bcr/config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Configuration for publish-to-bcr
2+
# The s2geometry Bazel module (MODULE.bazel) is located in the src/ directory
3+
moduleRoots:
4+
- "src"

‎.bcr/src/metadata.template.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"homepage": "https://github.com/google/s2geometry",
3+
"maintainers": [
4+
{
5+
"email": "vtsao@openai.com",
6+
"github": "vtsao-openai",
7+
"github_user_id": 176426301,
8+
"name": "Vincent Tsao"
9+
},
10+
{
11+
"github": "jmr",
12+
"github_user_id": 949741,
13+
"name": "Jesse Rosenstock"
14+
}
15+
],
16+
"repository": [
17+
"github:google/s2geometry"
18+
],
19+
"versions": [],
20+
"yanked_versions": {}
21+
}

‎.bcr/src/presubmit.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
matrix:
2+
platform:
3+
- ubuntu2404
4+
- macos
5+
- macos_arm64
6+
bazel: [7.x, 8.x, rolling]
7+
tasks:
8+
verify_targets:
9+
name: Verify build targets
10+
platform: ${{ platform }}
11+
bazel: ${{ bazel }}
12+
build_flags:
13+
- "--cxxopt=-std=c++17"
14+
- "--host_cxxopt=-std=c++17"
15+
build_targets:
16+
- "@s2geometry//:s2"
17+
test_targets:
18+
- "@s2geometry//:all"
19+
test_flags:
20+
- "--cxxopt=-std=c++17"
21+
- "--host_cxxopt=-std=c++17"

‎.bcr/src/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": "{REPO}-{VERSION}/src",
4+
"url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/{TAG}.tar.gz"
5+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Automated publication to Bazel Central Registry (BCR)
2+
# See https://github.com/bazel-contrib/publish-to-bcr
3+
4+
name: Publish to BCR
5+
6+
on:
7+
# Automatically publish when a release is created
8+
release:
9+
types: [released]
10+
11+
# Allow manual triggering for testing or retry
12+
workflow_dispatch:
13+
inputs:
14+
tag_name:
15+
description: 'Git tag to publish (e.g., v0.13.0)'
16+
required: true
17+
type: string
18+
19+
jobs:
20+
publish:
21+
uses: bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@v1.0.0
22+
with:
23+
tag_name: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.tag_name }}
24+
# Enable attestations for enhanced security
25+
attest: true
26+
permissions:
27+
contents: write
28+
id-token: write
29+
attestations: write
30+
secrets:
31+
# This secret must be set in repository settings
32+
# See .bcr/README.md for setup instructions
33+
publish_token: ${{ secrets.BCR_PUBLISH_TOKEN }}

0 commit comments

Comments
 (0)