Skip to content

Commit aed3185

Browse files
mmorel-35mmorel-35
committed
Add BCR workflow for Bazel Central Registry publishing
Signed-off-by: Matthieu MOREL <matthieu.morel35@gmail.com>
1 parent f8c573d commit aed3185

File tree

5 files changed

+230
-0
lines changed

5 files changed

+230
-0
lines changed

‎.bcr/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Bazel Central Registry (BCR) Publishing
2+
3+
This directory contains configuration files for automatically publishing `fast_float` releases to the [Bazel Central Registry (BCR)](https://github.com/bazelbuild/bazel-central-registry).
4+
5+
## Overview
6+
7+
When a new release is published on GitHub, the workflow defined in `.github/workflows/publish-to-bcr.yml` automatically:
8+
1. Creates a new entry in the BCR with the release version
9+
2. Opens a pull request to the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository
10+
3. Allows BCR maintainers to review and merge the update
11+
12+
This makes the new version of `fast_float` available to all Bazel users through the standard module system.
13+
14+
## Files in This Directory
15+
16+
### `metadata.template.json`
17+
Contains repository metadata including:
18+
- Project homepage
19+
- Maintainer information (name, email, GitHub username)
20+
- Repository references
21+
22+
This information is used to populate the BCR entry's `metadata.json` file.
23+
24+
### `source.template.json`
25+
Defines how to fetch the source code for each release:
26+
- URL pattern for release archives
27+
- Archive strip prefix configuration
28+
- Integrity hash (auto-generated during publishing)
29+
30+
### `presubmit.yml`
31+
Specifies the CI tests that BCR will run before accepting a new version:
32+
- Platforms to test on (Linux, macOS, Windows)
33+
- Bazel versions to test with
34+
- Build targets to verify
35+
36+
## How the Publishing Workflow Works
37+
38+
The publishing process is automated through GitHub Actions:
39+
40+
1. **Trigger**: When you create a new release on GitHub (or manually trigger the workflow)
41+
2. **Build**: The workflow uses [bazel-contrib/publish-to-bcr](https://github.com/bazel-contrib/publish-to-bcr) reusable workflow
42+
3. **Generate**: Creates BCR entry files from the templates in this directory
43+
4. **Submit**: Opens a pull request to the Bazel Central Registry
44+
5. **Review**: BCR maintainers review and merge the PR
45+
46+
## Setting Up the Personal Access Token (PAT)
47+
48+
The publishing workflow requires a GitHub Personal Access Token with appropriate permissions to:
49+
- Push to a fork of the Bazel Central Registry
50+
- Open pull requests against the upstream BCR
51+
52+
### Creating a Personal Access Token
53+
54+
1. **Navigate to GitHub Settings**
55+
- Go to https://github.com/settings/tokens
56+
- Or: Click your profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic)
57+
58+
2. **Generate New Token**
59+
- Click "Generate new token (classic)"
60+
- Give it a descriptive name, e.g., "BCR Publishing for fast_float"
61+
- Set an appropriate expiration (recommended: 1 year with calendar reminder to renew)
62+
63+
3. **Select Required Scopes**
64+
- ✅ **`repo`** (Full control of private repositories) - Required for accessing repository details
65+
- ✅ **`workflow`** (Update GitHub Action workflows) - Required for the publishing action
66+
67+
4. **Generate and Copy**
68+
- Click "Generate token" at the bottom
69+
- **Important**: Copy the token immediately - you won't be able to see it again!
70+
71+
5. **Add as Repository Secret**
72+
- Go to the fast_float repository settings
73+
- Navigate to: Settings → Secrets and variables → Actions
74+
- Click "New repository secret"
75+
- Name: `BCR_PUBLISH_TOKEN`
76+
- Value: Paste the token you copied
77+
- Click "Add secret"
78+
79+
### Important Notes
80+
81+
- **Classic PATs vs Fine-grained PATs**: Currently, you must use a "Classic" PAT. Fine-grained PATs don't yet support opening pull requests against public repositories (though GitHub is working on this).
82+
83+
- **Token Security**: Keep the token secure and never commit it to the repository. GitHub Secrets are encrypted and only exposed to authorized workflows.
84+
85+
- **Token Expiration**: Set a calendar reminder before your token expires to generate a new one, otherwise the publishing workflow will fail.
86+
87+
- **Permissions Required**: The token needs both `repo` and `workflow` scopes to function properly.
88+
89+
## Fork Requirements
90+
91+
The publishing workflow requires a fork of the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository:
92+
93+
- The fork should be in the repository owner's account or organization
94+
- The PAT must have write access to this fork
95+
- The workflow will push changes to the fork and open PRs from there to the upstream BCR
96+
97+
## Manual Triggering
98+
99+
You can manually trigger the publishing workflow:
100+
101+
1. Go to the Actions tab in the GitHub repository
102+
2. Select "Publish to BCR" workflow
103+
3. Click "Run workflow"
104+
4. Enter the tag name (e.g., `v6.1.6`)
105+
5. Click "Run workflow"
106+
107+
This is useful for:
108+
- Republishing a release if the automatic workflow failed
109+
- Publishing an older release that wasn't automatically published
110+
- Testing the workflow
111+
112+
## Troubleshooting
113+
114+
### Publishing Workflow Fails
115+
116+
1. **Check the workflow logs** in the Actions tab for specific error messages
117+
2. **Verify the PAT** is still valid and has the correct permissions
118+
3. **Confirm the fork exists** and the PAT has access to it
119+
4. **Check the template files** in this directory are valid JSON
120+
121+
### Pull Request Not Opening
122+
123+
1. **Verify PAT permissions** - must include `repo` and `workflow` scopes
124+
2. **Check fork configuration** - ensure the BCR fork exists and is accessible
125+
3. **Review workflow inputs** - ensure the tag name matches the actual release tag
126+
127+
### BCR Presubmit Tests Fail
128+
129+
1. **Review presubmit.yml** to ensure test configuration is correct
130+
2. **Check build targets** are valid in the new version
131+
3. **Verify MODULE.bazel** and BUILD files are properly configured
132+
4. The BCR maintainers may provide feedback on the pull request
133+
134+
## Updating Configuration
135+
136+
### To Update Maintainer Information
137+
138+
Edit `metadata.template.json` and update the maintainers array.
139+
140+
### To Change Test Configuration
141+
142+
Edit `presubmit.yml` to modify:
143+
- Platforms to test on
144+
- Bazel versions to test with
145+
- Build targets to verify
146+
147+
### To Modify Source Archive Settings
148+
149+
Edit `source.template.json` if the release archive structure changes.
150+
151+
## Resources
152+
153+
- [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
154+
- [publish-to-bcr Documentation](https://github.com/bazel-contrib/publish-to-bcr)
155+
- [Bzlmod User Guide](https://bazel.build/docs/bzlmod)
156+
- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
157+
158+
## Support
159+
160+
If you encounter issues with BCR publishing:
161+
1. Check the [publish-to-bcr issues](https://github.com/bazel-contrib/publish-to-bcr/issues)
162+
2. Review [BCR submission guidelines](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md)
163+
3. Open an issue in the fast_float repository for project-specific problems

‎.bcr/metadata.template.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"homepage": "https://github.com/fastfloat/fast_float",
3+
"maintainers": [
4+
{
5+
"email": "daniel@lemire.me",
6+
"github": "lemire",
7+
"name": "Daniel Lemire",
8+
"github_user_id": 391987
9+
}
10+
],
11+
"repository": [
12+
"github:fastfloat/fast_float"
13+
],
14+
"versions": [],
15+
"yanked_versions": {}
16+
}

‎.bcr/presubmit.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
matrix:
2+
platform:
3+
- debian10
4+
- ubuntu2004
5+
- ubuntu2204
6+
- macos
7+
- macos_arm64
8+
- windows
9+
bazel:
10+
- 9.*
11+
- 8.x
12+
- 7.x
13+
- 6.x
14+
tasks:
15+
verify_targets:
16+
name: Verify build targets
17+
platform: ${{ platform }}
18+
bazel: ${{ bazel }}
19+
build_targets:
20+
- '@fast_float'

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

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Publish to BCR
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
# Allow manual triggering from GH UI
8+
workflow_dispatch:
9+
inputs:
10+
tag_name:
11+
description: 'Tag name to publish (e.g., v1.2.3)'
12+
required: true
13+
type: string
14+
15+
permissions:
16+
id-token: write
17+
attestations: write
18+
contents: write
19+
20+
jobs:
21+
publish:
22+
uses: bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@v1.0.0
23+
with:
24+
tag_name: ${{ github.event.release.tag_name || inputs.tag_name }}
25+
secrets:
26+
publish_token: ${{ secrets.BCR_PUBLISH_TOKEN }}

0 commit comments

Comments
 (0)