When SDKs are published from one repository, npm, Swift Package Manager and Maven Central each ask something different.
npm wants a package's first version published by a person, since trusted publishing only takes over a package that
exists. Swift Package Manager wants a Git repository with Package.swift at its root, so a monorepo needs a public
copy. Maven Central wants a namespace you prove with a DNS record, and every file signed by a GPG key it can find on a
keyserver. I shipped five SDKs this way on October 26, 2026 (JavaScript, React, React Native, Swift and Android), from
one private repository. Here is each registry, and every place it broke.
One repository, three registries#
Every SDK lives in the same repository as the product, so that a change to the widget and to the SDKs that show it can land in one pull request. Each registry gets its own workflow, run by hand from the main branch, a dry run by default:
gh workflow run release-npm.yml # checks and packs, publishes nothing
gh workflow run release-npm.yml -f dry-run=false # publishes| SDKs | Registry | What a release is | Credential |
|---|---|---|---|
| JavaScript, React, React Native | npm | npm publish of each package | none: trusted publishing |
| Swift | its own public Git repository | a commit and a tag on a copy | a deploy key |
| Android (a library and its Compose one) | Maven Central | one signed upload of both | a portal token and a GPG key |
One file says each SDK's version, and a test holds every manifest to it, so the three npm packages, the Swift tag and the Gradle version can't drift apart.
npm: the first version comes from your machine#
Trusted publishing lets a GitHub Actions workflow publish with a short-lived token from GitHub, with no npm token stored anywhere. The catch: you set up a trusted publisher on a package's settings page, and a package that doesn't exist yet has no settings page. So the first version of every package goes out from a terminal:
npm login
npm publish --access public # in each package's folderMy first try failed with E403: npm refused to publish from an account without two-factor authentication. With it
on, npm asked for the passkey once per package, and 0.1.0 of the three went out.
Then, for each package, add the trusted publisher (the package's Settings → Trusted publishing, or npm trust
from the command line), naming the repository and the workflow file, with npm publish allowed: a new one allows
only npm stage publish otherwise. Add them just before the first release from CI. A trusted publisher that hasn't
published within two days of being made expires, and an expired one can't be edited, only deleted and made again.
The workflow needs one permission and a recent npm (11.5.1 or later; Node 26's has it):
permissions:
contents: read
id-token: write # npm's trusted publishing
jobs:
publish:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version-file: sdks/.node-version
registry-url: https://registry.npmjs.org
- run: npm ci
working-directory: sdks
# One package here; the real workflow runs a script that publishes each one and skips a version npm already has.
- run: npm publish --workspace @swingback/js
working-directory: sdksOnce it works, set each package's publishing access to require two-factor authentication and disallow tokens: the workflow keeps publishing, and no stolen token can.
One thing to leave out: provenance. npm makes no provenance statement for a package built from a private repository, and asking for it fails the publish.
Swift: a public copy with Package.swift at its root#
Swift Package Manager installs a package from a Git repository: it reads Package.swift at the repository's root,
at a tag that is a semantic version. It has no way to point at a folder inside someone's monorepo. So a release
writes a copy: a script puts the package, its tests, the protocol fixtures the tests read, the README and the license
into an empty folder, and nothing else. Then the workflow tests the copy itself, on macOS, before pushing it:
- name: The public copy
run: sdks/scripts/swift-copy.sh "$RUNNER_TEMP/copy"
- name: Its tests, in the copy itself
run: swift test --package-path "$RUNNER_TEMP/copy"
- name: Push it, tagged with its version
if: ${{ !inputs.dry-run }}
env:
DEPLOY_KEY: ${{ secrets.SWIFT_DEPLOY_KEY }}
run: sdks/scripts/swift-push.sh "$RUNNER_TEMP/copy" A release is one commit on the copy's main, naming the source commit, and a tag like 0.1.0. Nothing of the private
repository's history goes there. The result is
Swingback-dev/swingback-swift, which you add in Xcode like any
other package.
Two things broke. The push uses a deploy key with write access, and GitHub refused it: a new organization has deploy keys turned off (its Settings → Member privileges). And the first real run failed a test that drives a real WebKit view: on a busy macOS runner, WebKit started slowly, and the answer came after the two seconds the test waited. Because the tests run before the push, nothing was published. The fix gave the tests' helper ten seconds:
/// Waits until `condition` holds, ten seconds at most: a busy CI runner's WebKit starts slowly.
@MainActor
func eventually(_ condition: () -> Bool) async {
let clock = ContinuousClock()
let deadline = clock.now + .seconds(10)
while !condition(), clock.now < deadline {
try? await Task.sleep(for: .milliseconds(5))
}
}Maven Central: a namespace and a GPG key#
Maven Central publishes under a namespace you own, such as dev.swingback. You register it on the
Central Portal and prove the domain with a TXT record whose value is the key the
portal shows. The record goes on the domain itself (for dev.swingback, on swingback.dev), not a subdomain. Check
that it answers before you press Verify Namespace: a check that ran too early is remembered for a while.
dig -t txt swingback.dev +shortThe portal then gives you a user token, the username and password the build uploads with.
Every file you upload must be signed, and Central checks the signatures against a public key it finds on a keyserver. I made an RSA key that signs with its primary key, in a keyring of its own, and that's where gpg stopped:
gpg: can't connect to the gpg-agent: File name too long
gpg: agent_genkey failed: No agent running
gpg: key generation failed: No agent runninggpg-agent listens on a Unix socket inside GNUPGHOME, and macOS caps a socket's path at 104 bytes. A keyring in a
deep temporary folder is past that. A short path fixes it:
export GNUPGHOME=/tmp/g && mkdir -m 700 -p "$GNUPGHOME"
gpg --quick-generate-key 'Your Name <you@example.com>' rsa4096 sign 3yNext, gpg --send-keys to keyserver.ubuntu.com failed. The keyserver's own upload form takes the key over HTTPS,
which curl can do:
gpg --armor --export <fingerprint> > public.asc
curl --data-urlencode keytext@public.asc https://keyserver.ubuntu.com/pks/add The private key, armored, and its passphrase become two repository secrets; the keyring on my machine was then
deleted. The Gradle side is the com.vanniktech.maven.publish plugin: it builds the release AAR, a sources jar and an
empty javadoc jar (Central accepts a placeholder), writes the POM, signs everything when a key is given, and
publishAndReleaseToMavenCentral uploads both libraries as one deployment. The dry run signs into the runner's local
Maven repository, which proves the key works before anything leaves. After a real upload, Central validates and
publishes; Gradle found the libraries about half an hour later. A release on Central can't be taken back, which is a
good reason for the dry run.
What I'd do again#
- Release by hand, from the main branch, dry run first. Each registry's mistakes are permanent in its own way.
- Test what users install. The Swift copy is tested as a copy; the npm packages are packed and checked before publishing.
- One version file, held by tests. Five SDKs at three registries drift the moment versions live in five places.
- Expect every first release to be manual. npm's first versions, Central's namespace, the Swift repository and its deploy key, the signing key: each was a one-time step a workflow couldn't do.
Where this came from#
These are Swingback's SDKs, which put a feedback widget, the roadmap and the changelog inside your app on the web, iOS and Android; the SDK docs list them. If you build with React Native, here is in-app feedback in React Native and Expo.
