Skip to content

feat(registry): Require and validate registry metadata on first publish #777

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s1gr1d merged 7 commits into from
Mar 20, 2026
+259 −55
Merged

feat(registry): Require and validate registry metadata on first publish #777

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3a8acc3
meta: Bump new development version
Mar 16, 2026
630f531
revert version
s1gr1d Mar 18, 2026
a20258c
meta: Bump new development version
s1gr1d Mar 19, 2026
24183a3
update docs
s1gr1d Mar 19, 2026
7dc0586
require `name` and docs url for all new packages
s1gr1d Mar 19, 2026
590b411
update doc
s1gr1d Mar 20, 2026
d939675
add registry variable column
s1gr1d Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 64 additions & 46 deletions docs/src/content/docs/targets/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,19 +16,19 @@ Avoid having multiple `registry` targets—it supports batching multiple apps an
| `apps` | Dict of app configs keyed by canonical name (e.g., `app:craft`) |
| `sdks` | Dict of SDK configs keyed by canonical name (e.g., `maven:io.sentry:sentry`) |

### App/SDK Options
### Per-package options

| Option | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Option | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `urlTemplate` | URL template for artifact download links in the manifest. Supports `{{version}}`, `{{file}}`, and `{{revision}}` variables. Primarily for apps and CDN-hosted assets—not needed for SDK packages installed from public registries (npm, PyPI, etc.) |
| `linkPrereleases` | Update for preview releases. Default: `false` |
| `checksums` | List of checksum configs |
| `onlyIfPresent` | Only run if matching file exists |
| `name` | Human-readable name (used when creating new packages) |
| `sdkName` | SDK identifier matching the SDK's `sdk_info.name` field in Sentry events (e.g., `sentry.javascript.react`). Will create the `sdks/` symlink. (used when creating new packages) |
| `packageUrl` | Link to package registry page, e.g., npmjs.com (used when creating new packages) |
| `mainDocsUrl` | Link to main documentation (used when creating new packages) |
| `apiDocsUrl` | Link to API documentation (used when creating new packages) |
| `linkPrereleases` | By default, the registry target is skipped when the version is a pre-release (e.g. `1.0.0-beta.1`). Set to `true` to publish registry entries for pre-releases as well. |
| `checksums` | List of checksum configs (see [Checksum Configuration](#checksum-configuration)) |
| `onlyIfPresent` | Only run if artifact matches the given filename pattern |
| `name` | Human-readable name for the platform or package (e.g. `"Sentry Browser SDK"` or `"Sentry Craft"`) - (used when creating new packages) |
| `sdkName` | SDK identifier matching the SDK's `sdk_info.name` field in Sentry events (e.g., `sentry.javascript.react`). Will create the `sdks/` symlink. (used when creating new packages) |
| `packageUrl` | Link to the package registry page (e.g. npmjs.com, PyPI, crates.io). Not required for `app` types (used when creating new packages) |
| `mainDocsUrl` | Link to the main documentation page. If omitted, Craft falls back to `repo_url` and emits a warning. (used when creating new packages) |
| `apiDocsUrl` | Link to the API documentation (e.g. pkg.go.dev, javadoc.io) - (used when creating new packages) |

### Checksum Configuration

Expand All @@ -38,31 +38,51 @@ checksums:
format: hex # or base64
```

## Example
## How a registry entry is built

Every time Craft publishes a release, it writes a version file (e.g. `packages/npm/@sentry/browser/1.2.3.json`) to the registry. The fields in that file come from different sources:

| Registry field | `.craft.yml` option | Source |
|-----------------|---------------------|-----------------------------------------------------------------------------------------------------|
| `canonical` | _(dict key)_ | The dict key in `.craft.yml` (e.g. `npm:@sentry/browser`). Set once on first publish (not updated). |
| `version` | _(automatic)_ | The release version being published |
| `created_at` | _(automatic)_ | The current timestamp at publish time |
| `repo_url` | _(automatic)_ | Auto-detected from the `origin` git remote. Overwritten on every publish |
| `name` | `name` | Your `.craft.yml` config. Applied on every publish, can be updated at any time |
| `package_url` | `packageUrl` | Your `.craft.yml` config. Applied on every publish, can be updated at any time |
| `main_docs_url` | `mainDocsUrl` | Your `.craft.yml` config. Applied on every publish, can be updated at any time |
| `api_docs_url` | `apiDocsUrl` | Your `.craft.yml` config. Applied on every publish, can be updated at any time |

The `canonical` field is the only one that cannot be changed after the first publish—it is written once and then validated for consistency on every subsequent run. To rename a canonical, you must manually update both the registry and your `.craft.yml` at the same time.

`repo_url` is always resolved automatically and cannot be configured per-package. By default, Craft reads the `origin` git remote (both HTTPS and SSH formats are supported). If auto-detection is not possible, configure it via a top-level `github` block:

```yaml
targets:
- name: registry
sdks:
'npm:@sentry/browser':
apps:
'app:craft':
urlTemplate: 'https://downloads.sentry-cdn.com/craft/{{version}}/{{file}}'
checksums:
- algorithm: sha256
format: hex
github:
owner: getsentry
repo: sentry-javascript
```

## Package Types
## Adding a new package

- **sdk**: Package uploaded to public registries (PyPI, NPM, etc.)
- **app**: Standalone application with version files in the registry
When a package does not yet exist in the registry, Craft creates the directory structure and initial manifest automatically on the first publish. No manual registry changes are needed.

## Creating New Packages
For this to succeed, certain fields must be present in your `.craft.yml` before you publish for the first time.

:::caution[Required metadata on first publish]

- **`name`** — required for all package types.
- **`mainDocsUrl`** — required for all package types. If omitted, Craft falls back to `repo_url` and emits a warning, but you should always set it explicitly.

- **`sdkName`** — required for SDK packages.
- **`packageUrl`** — required for SDK packages
:::

When you introduce a new package that doesn't yet exist in the release registry, Craft will automatically create the required directory structure and initial manifest on the first publish.
After the first publish, you can add or update any of these fields in `.craft.yml` and they will be applied to the manifest on the next release.

Supply `name`, `packageUrl`, `sdkName` and `mainDocsUrl` so the release registry entry is added to the registry for the first time (existing packages just need `onlyIfPresent` since the manifest already exists):
### Example: New SDK package

A package uploaded to public registries (PyPI, NPM, etc.)

```yaml
targets:
Expand All @@ -73,25 +93,23 @@ targets:
sdkName: 'sentry.javascript.wasm'
packageUrl: 'https://www.npmjs.com/package/@sentry/wasm'
mainDocsUrl: 'https://docs.sentry.io/platforms/javascript/'
# Optional fields for SDKs with API docs:
apiDocsUrl: 'https://pkg.go.dev/github.com/getsentry/sentry-go'
```

## Manifest Metadata

### `repo_url`

The `repo_url` field is automatically set on every publish—it is not user-configurable per target. Craft resolves it in two ways:

1. **Auto-detection (default):** Craft reads the `origin` git remote URL and extracts the owner and repo. Both HTTPS (`https://github.com/org/repo.git`) and SSH (`git@github.com:org/repo.git`) formats are supported. For most repositories, no configuration is needed.
### Example: New App with downloadable artifacts

2. **Explicit config (rare):** If auto-detection isn't possible (e.g., the remote is not on `github.com`), you can provide it via a top-level `github` block in `.craft.yml`:
```yaml
github:
owner: getsentry
repo: sentry-javascript
```
A standalone application with version files in the registry

The value is always overwritten on every publish, so it stays in sync with the actual repository.

### Other metadata

When specified, the metadata fields (`name`, `sdkName`, `packageUrl`, `mainDocsUrl`, `apiDocsUrl`) are applied to every release, allowing you to update package metadata by changing your `.craft.yml` configuration.
```yaml
targets:
- name: registry
apps:
'app:craft':
name: 'Sentry Craft'
mainDocsUrl: 'https://github.com/getsentry/craft'
urlTemplate: 'https://downloads.sentry-cdn.com/craft/{{version}}/{{file}}'
checksums:
- algorithm: sha256
format: hex
```
Loading
Loading