This document describes the reproducible, public part of a SourceBraid release. Store credentials, account verification, legal attestations, review accounts, and final submission decisions are intentionally maintained outside the public repository.
The iOS app is published in the App Store as 1.0.1. The Chrome Web Store and
public ChatGPT/Codex directory releases remain separate maintainer actions and
must not be described as available before their listings are live. The first
coordinated Chrome and OpenAI plugin release uses 1.0.1 so all available
clients start from the same customer-facing version.
- Build and tag releases from a clean commit on the public
mainbranch. - Never merge private repository history into this repository.
- Never include
website/,web-clips/, credentials, local configuration, Keychain data, caches, indexes, or generated build directories in a release. - Use the checked-in package builders. They construct archives from explicit allowlists instead of copying the repository broadly.
- Preserve source provenance and use only synthetic or redistributable content in release screenshots and examples.
- Every pull-request commit must carry a DCO
Signed-off-by:trailer.
Before creating the first release candidate, align these customer-facing versions:
- Chrome:
versioninchrome-extension/sourcebraid/manifest.json. - Local Codex/optional skills package:
versionincodex-plugin/sourcebraid/.codex-plugin/plugin.json. - Hosted ChatGPT MCP:
versioninchatgpt-mcp/package.jsonand its server metadata. - iOS app and Share Extension:
MARKETING_VERSIONinios/SourceBraid.xcodeproj/project.pbxproj.
Chrome versions use one to four dot-separated integers. The plugin uses semantic
versioning. After the first iOS upload, increase CURRENT_PROJECT_VERSION for
every new binary while keeping the app and Share Extension build numbers equal.
The first iOS publication uses the SourceBraid identities:
- app:
de.patrickschiller.sourcebraid; - Share Extension:
de.patrickschiller.sourcebraid.share; - App Group:
group.de.patrickschiller.sourcebraid; - shared Keychain group:
$(AppIdentifierPrefix)de.patrickschiller.sourcebraid.shared.
Run from the repository root:
git status --short --branch
node --test tests/capture-utils.test.js
python3 -m unittest discover -s tests -p "test_*.py"
npm --prefix chatgpt-mcp ci
npm --prefix chatgpt-mcp test
npm --prefix chatgpt-mcp run buildRun the unsigned iOS build from ios/:
python3 ../scripts/validate_ios_release.py
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild \
-project SourceBraid.xcodeproj \
-scheme SourceBraid \
-sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO \
buildDo not release while a required check fails or the worktree contains unrelated changes.
The unpacked extension source lives in chrome-extension/sourcebraid. Build the
Manifest V3 archive from its explicit allowlist:
python3 scripts/build_chrome_package.py
unzip -l dist/sourcebraid-chrome-v*.zipThe script prints the package path, version, SHA-256 digest, and file count. The
ZIP must contain manifest.json at its root and must not contain source archives,
the private website, plugin configuration, iOS sources, tests, Git metadata, or
local settings.
Build the optional local-runtime archive:
python3 scripts/build_plugin_package.py
unzip -l dist/sourcebraid-plugin-skills-v*.zipThe public package contains the three SourceBraid skills, their OpenAI metadata, the dependency-free CLI, and listing assets. The builder intentionally removes the local MCP server declaration and app entries from the packaged manifest. Local repository installations can continue to use the complete plugin source. This ZIP needs a runtime with Python and GitHub credentials. It is not a standalone normal-ChatGPT connection and is not the primary OpenAI submission.
The separate Worker in chatgpt-mcp/ is prepared for
https://mcp.sourcebraid.com/mcp; it is not deployed. Build the allowlisted
service source package and synthetic reviewer archive:
python3 scripts/build_mcp_package.py
python3 scripts/build_review_fixture.py \
--output dist/sourcebraid-review-fixture-v1.0.1.zipThe review ZIP contains only three synthetic Markdown clips and their three
metadata shards. It does not read or copy a user's archive. Follow
docs/CHATGPT_MCP_DEPLOYMENT.md for account,
domain, KV, OAuth, and live smoke checks. A Worker dry-run or source ZIP is not a
successful production deployment.
The primary 1.0.1 ChatGPT submission is With MCP, using the hosted
read-only service after deployment and live tests. Supply the actual public
HTTPS endpoint and complete domain verification. Do not submit the intended
https://mcp.sourcebraid.com/mcp URL as a working service before it is live.
Use marketing/OPENAI_MCP_SUBMISSION.md
as the submission source of truth. It contains the copy-ready listing, starter
prompts, reviewer setup, five positive tests, three negative tests, release
notes, privacy disclosures, and the final portal checklist. Before submitting:
- confirm
Apps Management: Writeaccess and the verified publisher identity; - build and inspect the hosted MCP source package and deploy the reviewed Worker with verified domain and OAuth configuration;
- seed the dedicated private review repository from the synthetic fixture ZIP and validate the live OAuth/search/fetch flow;
- restrict its review PAT to Contents read-only on that one repository and provide credentials only through OpenAI's protected submission fields;
- select country availability deliberately and complete the policy attestations; and
- submit for review, then publish only after approval.
Follow the current OpenAI submission guide and plugin packaging guide when the portal or required fields change. Builds, deployment, review submission, approval, and publication are distinct states. The optional local skills kit describes different capabilities and must not be copied into the hosted read-only listing.
Build and verify the allowlisted artifacts, submission documents, graphics, and synthetic fixture from the final reviewed commit:
python3 scripts/build_release.py --verify-reproducible --require-clean
python3 scripts/build_release.py --verify dist/sourcebraid-release-v1.0.1Use the generated RELEASE_MANIFEST.json and SHA256SUMS as the artifact and
digest record. Do not hard-code a ZIP digest in documentation: runtime changes
require rebuilding and verifying the bundle. The builders export only explicit
public allowlists, never broad copies or private repository history.
Confirm that the SourceBraid bundle identifiers, App Group, and Keychain access
group are registered for the selected Apple Developer team before enabling
signing. First validate the unsigned simulator build above. Then use the archive
and export commands in ios/README.md. Validate the archived
.app with scripts/validate_ios_release.py --app-bundle PATH before uploading
it. This catches stale icons and mismatched app/extension versions in the actual
package rather than only checking the Xcode sources.
Signing and App Store upload credentials are not part of this repository. Never commit provisioning profiles, certificates, export credentials, review tokens, or App Store Connect API keys.
Validate the user-facing repository bootstrap workflow without changing a repository:
python3 scripts/setup_github.py --dry-runWithout --repo, the script targets
AUTHENTICATED_USER/sourcebraid-private. It writes a token-free
sourcebraid-config.json, preserves existing repositories and support files,
and refuses to configure a public archive. Build the standalone release artifact
with the same embedded allowlist:
python3 scripts/build_setup_package.py
python3 dist/sourcebraid-github-setup-v1.0.1.py --helpThe setup and builder must avoid printing or embedding credentials and must
never include web-clips/, website/, or files outside the documented support
allowlist.
Validate .agents/plugins/marketplace.json and
codex-plugin/sourcebraid/.codex-plugin/plugin.json before tagging. The
marketplace entry uses the repository-local plugin path and is consumed from
GitHub with both paths included in the sparse checkout:
codex plugin marketplace add patrickschiller/sourcebraid \
--ref v1.0.1 \
--sparse .agents/plugins \
--sparse codex-plugin/sourcebraid
codex plugin add sourcebraid@sourcebraidDo not advertise that command as live before the referenced tag exists.
- Review the complete diff from the previous release tag, or the repository root commit for the first release.
- Record the passing check results and package SHA-256 digests.
- Create an annotated version tag on the reviewed public commit.
- Push the tag to the public repository.
- Attach the Chrome ZIP, hosted MCP source ZIP, optional local skills ZIP, standalone GitHub setup script, synthetic fixture, and generated digest record to the corresponding GitHub release when artifacts are distributed.
- Verify that every published archive can be traced back to the tagged commit.
Store review and publication remain separate maintainer actions. A GitHub tag or release must not imply that a store submission has already been approved.