native-packages 0.6.0 → 0.7.0

data/docs/_guides/native-recipes.md

@@ -0,0 +1,189 @@
+---
+title: macOS and Windows installers
+description: Connect your DMG or Inno Setup script to the same build and publication process as your Linux packages.
+nav_order: 5
+---
+
+# macOS and Windows installers
+
+This guide shows how to connect an existing DMG or Inno Setup script to
+native-packages. You supply a built app and a packaging script. The build
+command checks the app, runs your script, and records the finished installer's
+checksum.
+
+Build **DMGs on macOS** and **Inno installers on Windows**. These targets use
+your native tools and do not need an nFPM executable.
+
+## Prepare your app
+
+Build the complete application first, including any libraries and supporting
+files. A macOS input can be `dist/Hello.app`. A Windows input can be a directory
+such as `dist/windows` containing `hello.exe` and its dependencies.
+
+If your inputs come from another job, download and unpack them before packaging.
+Native targets require a local directory and use `build --version`; they do
+not accept `build --release` downloads directly.
+
+## Configure the targets
+
+Here is a complete configuration for an ARM64 Mac app and an x86-64 Windows app:
+
+```yaml
+schema: 1
+tool:
+  version: '0.7.0'
+  nfpm: '2.47.0'
+nfpm:
+  name: hello
+  description: A small greeting application
+  maintainer: Your Name <you@example.com>
+  license: MIT
+release:
+  repository: your-name/hello
+targets:
+  macos-arm64:
+    platform: macos
+    arch: arm64
+    formats: [dmg]
+    input:
+      kind: directory
+      local: dist/Hello.app
+    native:
+      command: [ruby, packaging/dmg.rb, '@PAYLOAD@', '@PACKAGE@']
+      output: 'hello-@TAG@-macos-arm64.dmg'
+  windows-amd64:
+    platform: windows
+    arch: amd64
+    formats: [inno]
+    input:
+      kind: directory
+      local: dist/windows
+    native:
+      command: [ruby, packaging/setup.rb, '@PAYLOAD@', '@PACKAGE@', '@VERSION@']
+      output: 'hello-@TAG@-windows-setup.exe'
+```
+
+The `nfpm` section still holds shared package metadata, and `tool.nfpm` keeps
+mixed-platform configurations consistent. Native targets use `native.command`
+to create their output.
+
+For Intel Macs, use `arch: amd64`. Use `arch: universal` for a build containing
+both Intel and ARM64 code. Architecture checks use Apple's `lipo`.
+
+## Write the packaging command
+
+`native.command` is a list of arguments. It must include `@PACKAGE@`:
+
+| Value | What your script receives |
+| --- | --- |
+| `@PAYLOAD@` | A temporary copy of the input to package. |
+| `@PACKAGE@` | The exact, absolute path where the output must be created. |
+| `@VERSION@` | App version, such as `1.2.3`. |
+| `@TAG@` | Release tag, such as `v1.2.3`. |
+
+Commands run in the configuration directory. They also receive
+`NATIVE_PACKAGES_TARGET`, `NATIVE_PACKAGES_VERSION`, and `SOURCE_DATE_EPOCH`.
+
+### A minimal DMG script
+
+For the `Hello.app` input above, create `packaging/dmg.rb`:
+
+```ruby
+require "fileutils"
+require "tmpdir"
+
+payload, output = ARGV
+abort "expected payload and output paths" unless payload && output
+abort "output already exists" if File.exist?(output)
+
+Dir.mktmpdir("hello-dmg-") do |staging|
+  FileUtils.cp_r(payload, File.join(staging, "Hello.app"), preserve: true)
+  File.symlink("/Applications", File.join(staging, "Applications"))
+  success = system("hdiutil", "create", "-volname", "Hello",
+    "-srcfolder", staging, "-format", "UDZO", output)
+  abort "DMG creation failed" unless success
+end
+
+abort "DMG verification failed" unless system("hdiutil", "verify", output)
+```
+
+This places the app and an Applications shortcut inside a compressed disk
+image. Adapt the volume name and app name to your project.
+
+### An Inno Setup script
+
+Keep your app's `.iss` recipe in the repository. Have `packaging/setup.rb`
+invoke your installed Inno compiler and pass it the three arguments above.
+The wrapper should:
+
+1. Use `@PAYLOAD@` as the source directory for the recipe's files.
+2. Map `@VERSION@` to the app and numeric installer version fields.
+3. Set the compiler's output directory and filename from `@PACKAGE@`.
+4. Fail if compilation fails.
+
+An Inno recipe also owns your app's identity, installation location, shortcuts,
+and uninstall behavior. See the
+[Inno command-line compiler documentation](https://jrsoftware.org/ishelp/topic_compilercmdline.htm)
+for invoking it from your wrapper.
+
+## Build on each host
+
+On the Mac:
+
+```sh
+native-packages doctor --target macos-arm64
+native-packages build --version 1.2.3 --target macos-arm64 --output dist/macos-packages
+```
+
+On Windows:
+
+```sh
+native-packages doctor --target windows-amd64
+native-packages build --version 1.2.3 --target windows-amd64 --output dist/windows-packages
+```
+
+`doctor` checks the host and the command's executable. Your script checks its
+additional tools, such as the Inno compiler. `validate` and `build --dry-run`
+do not execute it.
+
+The build checks Mach-O or PE architecture, runs the script, and checks that
+it produced exactly the declared DMG or EXE. Test installation, startup,
+upgrades, and removal separately for your app.
+
+## Preserve the prepared input
+
+Package the copy at `@PAYLOAD@`. A top-level `.app` keeps its basename; other
+input directories are copied into a directory named `payload`.
+
+The copy preserves file modes and safe internal relative symlinks, including
+framework links. Dangling links, links escaping the input, and special files
+are rejected. Your recipe and output hooks must leave the copied input
+unchanged. Use your own temporary staging directory when arranging files.
+
+The command must create only its declared output in the destination directory.
+Keep logs and temporary files elsewhere.
+
+## Sign before recording checksums
+
+For DMG targets, providing complete Apple credentials enables automatic input
+signing and DMG notarization. Follow [Apple signing and notarization](apple-notarization.md).
+The DMG script must preserve the signed app when copying it into the image.
+
+For Windows, use an `after_package` hook to sign the output:
+
+```yaml
+after_package: [pwsh, -File, packaging/sign.ps1, '@PACKAGE@']
+```
+
+This runs before the output hash is recorded. It must preserve the output's
+filename and file set. Do not sign or otherwise change the installer after
+building; publication would reject the changed hash.
+
+MSIX is a separate Windows format. It uses package metadata and file mappings
+instead of `native.command`; see [Supported platforms](../_reference/platforms.md#msix).
+
+## Combine and publish
+
+Use [Building across platforms](multi-platform.md) to combine these directories
+with Linux builds. If your configuration also has AUR or Homebrew templates,
+that guide explains how to generate recipes after all native packages exist.

data/docs/_guides/prereleases.md

@@ -0,0 +1,72 @@
+---
+title: Prereleases
+description: Build and publish alpha, beta, and release candidate packages with explicit version rules.
+nav_order: 9
+---
+
+# Prereleases
+
+Use a prerelease to let people test an upcoming version before the stable
+release. native-packages supports alpha, beta, and release candidate packages
+for **DEB, RPM, DMG, and Inno Setup**.
+
+## Enable preview versions
+
+Add this to your release settings:
+
+```yaml
+release:
+  repository: your-name/hello
+  prereleases: true
+```
+
+Then build with a version such as:
+
+```sh
+native-packages build --version 1.2.3-alpha.1
+```
+
+Accepted suffixes are `-alpha.N`, `-beta.N`, and `-rc.N`, where `N` is a positive
+integer. Build metadata suffixes such as `+build.5` are not accepted.
+Stable versions such as `1.2.3` continue to work.
+
+DEB and RPM use the packaging helper's version conversion; for example,
+`1.2.3-alpha.1` becomes `1.2.3~alpha.1`. Keep the normal SemVer conversion
+enabled and do not override the prerelease field.
+
+## Keep distribution recipes for stable releases
+
+The simplest setup is a separate preview configuration with supported formats
+and no `templates`:
+
+```sh
+native-packages --config native-packages.preview.yaml build \
+  --version 1.2.3-beta.1
+```
+
+If a native build shares a configuration with stable AUR or Homebrew recipes,
+you can use `--defer-recipes` to produce its preview package. Those recipes
+cannot be finalized for a prerelease, and the deferred build cannot be passed
+to `publish --from`. Collect the native output through your application's
+release job, or use a separate preview configuration for normal CLI publication.
+
+## Publish to a GitHub prerelease
+
+Create the matching GitHub release, such as `v1.2.3-alpha.1`, and mark it as a
+prerelease. Then publish a complete, non-deferred build:
+
+```sh
+native-packages publish --from dist/packages/1.2.3-alpha.1 --to github
+```
+
+The command checks that the existing release is marked as a prerelease. It
+does not create the release or change its status. Downstream recipe publication
+is reserved for stable versions.
+
+## Native installer versions
+
+Your DMG or Inno script receives the app version, including the suffix.
+If the installer needs numeric version fields, define that mapping in your
+app's script. Test that alpha 2 upgrades alpha 1 and that the stable version
+upgrades the previews. The packaging tool does not choose that ordering policy
+for your application.

data/docs/_guides/publishing.md

@@ -0,0 +1,143 @@
+---
+title: Publishing a release
+description: Build packages from local files or GitHub release assets and publish the verified result.
+nav_order: 3
+---
+
+# Publishing a release
+
+Once you have [built and tested your packages](getting-started.md), you can
+attach them to a GitHub release. This guide covers both local inputs and
+binaries that are already uploaded to a release.
+
+## 1. Choose the release repository
+
+Add your GitHub repository to `native-packages.yaml` before building:
+
+```yaml
+release:
+  repository: your-name/hello
+```
+
+This is where native-packages downloads release inputs and uploads packages.
+It can be a separate repository from your application's source code.
+
+## 2. Build your packages
+
+### From local files
+
+Use the same command as during development:
+
+```sh
+native-packages build --version 1.2.3
+```
+
+This reads each target's `input.local`. You can build and test the packages
+before creating a GitHub release.
+
+### From an existing GitHub release
+
+To package binaries your release workflow has already uploaded, declare each
+target's release asset name:
+
+```yaml
+input:
+  kind: archive
+  local: dist/hello_@VERSION@_linux_amd64.tar.gz
+  release_asset: hello_@VERSION@_linux_amd64.tar.gz
+```
+
+The local path remains useful for development. `release_asset` is the exact
+filename attached to the GitHub release; `@VERSION@` becomes `1.2.3`.
+
+Upload a `checksums.txt` alongside the input archives. It must contain SHA-256
+hashes with the release filenames. For example, run this in the directory
+containing the archive, then upload both files through your release workflow:
+
+```sh
+sha256sum hello_1.2.3_linux_amd64.tar.gz > checksums.txt
+```
+
+For several binary inputs, include all of them in the same checksum file.
+If your workflow uses another filename, set `release.checksums` to that name.
+
+Now build from the published release:
+
+```sh
+native-packages build --release v1.2.3
+```
+
+The command downloads the inputs, verifies their published hashes, and builds
+packages in `dist/packages/1.2.3/`. It skips `before_build` hooks. Every binary
+release input needs a matching checksum.
+
+DMG and Inno targets use prepared local directories. Download and unpack their
+inputs in the native build job, then use `--version`. See
+[macOS and Windows installers](native-recipes.md).
+
+## 3. Upload the finished build
+
+Install and authenticate the [GitHub CLI](https://cli.github.com/), and create
+release `v1.2.3` in the configured repository using your normal release process.
+The release must exist before you publish packages.
+
+```sh
+native-packages publish --from dist/packages/1.2.3 --to github
+```
+
+Before uploading, native-packages verifies the recorded file hashes, the
+configuration, and the required targets and formats. Keep the build directory
+intact and use the same configuration you built with.
+
+The upload includes the package files, a recipe archive if one was generated,
+and `packaging-checksums.txt`. Your original `checksums.txt` is preserved.
+Files with matching names on the release are replaced, so publish the tested
+build you intend users to download.
+
+## Publish selected targets
+
+By default, publication requires every configured target and all its formats.
+If one configuration includes targets released by separate jobs, name exactly
+which complete targets this build contains:
+
+```sh
+native-packages build --release v1.2.3 \
+  --target linux-amd64 --output dist/linux-packages
+native-packages publish --from dist/linux-packages --to github \
+  --target linux-amd64
+```
+
+All formats for `linux-amd64` must be present, and the directory must contain
+no additional targets. A build made with `--format deb` cannot be published
+if that target also declares RPM.
+
+To combine builds from several jobs, follow
+[Building across platforms](multi-platform.md). Builds with deferred recipes
+must be finalized before publication.
+
+## Update distribution recipes
+
+For AUR, Homebrew, or another downstream repository, first configure its
+[recipe templates and destination](distribution-recipes.md). Then stage and
+review the generated update:
+
+```sh
+native-packages stage aur dist/packages/1.2.3/recipes
+native-packages diff aur
+native-packages publish aur
+```
+
+Once this is part of your tested release process, you can publish configured
+destinations together:
+
+```sh
+native-packages publish --from dist/packages/1.2.3 --to github,aur,homebrew
+```
+
+GitHub pull requests and GitLab merge requests require a reviewed description
+with `--body-file`. Publish those destinations individually.
+
+## Next steps
+
+Set up [GitHub Actions](github-actions.md) to run packaging for each release.
+For alpha and beta versions, read [Prereleases](prereleases.md).

data/docs/_guides/release-signing.md

@@ -0,0 +1,137 @@
+---
+title: Release signatures and attestations
+description: Share release signing machinery while keeping application keys, approval policy and build identity separate.
+nav_order: 10
+---
+
+# Release signatures and attestations
+
+Publisher signatures authorize release downloads. Build attestations identify
+which repository, workflow and commit produced an artifact. Use both when your
+application downloads its own updates. Neither proves the source code is safe.
+These features are available in native-packages 0.7.0 and later. Use the
+released gem for local commands and pin composite actions to the reviewed
+commit behind the corresponding release tag.
+
+## Keep the trust policy in the application
+
+Each application owns its private key, committed public key, updater verification
+and release approval rules. Do not share a key between unrelated applications,
+store private keys in native-packages, or fetch an updater's trust root from the
+same release it is checking. There is no unsigned fallback when signing is used.
+
+Store the private PKCS#8 PEM key in a protected GitHub environment in the
+application repository. Restrict that environment to release tags and require
+maintainer approval. Keep an encrypted backup outside GitHub. Approval should
+cover the exact commit, build results and artifacts, not just a version label.
+Only the final signing job needs this secret. PR/build jobs do not.
+
+This uses GitHub-hosted key custody, not an independent offline authority.
+Maintain separate Apple notarization and Windows Authenticode credentials where
+needed; a checksum signature does not replace either platform's signing system.
+
+## Generate, sign and verify locally
+
+Put only the finished release artifacts in a staging directory. Do not include
+private keys, source checkout folders or intermediate build files. Keep the
+public key outside this directory too.
+
+```sh
+native-packages release-checksums dist/release --output dist/release/checksums.txt
+native-packages sign-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
+native-packages verify-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
+```
+
+Provide the private PEM through `NATIVE_PACKAGES_SIGNING_KEY` using your secret
+manager. `--key-env VARIABLE` selects another environment variable, not its
+value. Never put a private key on a command line or enable shell tracing.
+Signing reads the key in-process, removes it from that process's environment,
+and creates no private key file. It does not promise secure erasure of Ruby or
+OpenSSL memory. Missing, malformed, wrong or non-Ed25519 keys fail closed.
+
+The output is a deterministic, sorted SHA-256 manifest plus a raw 64-byte
+Ed25519 signature over its exact bytes. The public-key file is 32 bytes encoded
+as 64 hex digits. This is Ed25519, not Ed25519ph. Signing verifies the listed
+files first; verification authenticates the manifest before reading its paths.
+Metadata is limited to 1 MiB. Filenames must be flat ASCII names beginning with
+a letter or digit, using letters, digits, dots, underscores, plus or minus.
+Symlinks, directories, duplicate names (including case collisions), path
+traversal and self-references are rejected. Existing outputs are not overwritten.
+Upload artifacts, `checksums.txt` and `checksums.txt.sig` together.
+
+These are explicit commands. Existing `build --release` and `publish` behavior
+is unchanged: they do not silently gain signature verification or signing.
+To verify a downloaded release, stage its files and explicitly run
+`verify-checksums` with your locally trusted public key before using those files.
+Package publication's separate `packaging-checksums.txt` is also unchanged.
+
+## Attest in the application's build job
+
+The examples use `v0.7.0` for readability. For release workflows, replace it
+with that release's reviewed full commit SHA, not a mutable branch.
+After producing the final package, before uploading it, add this step to the
+job that built it:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+  attestations: write
+steps:
+  # Existing checkout, build, platform signing and packaging steps go here.
+  - uses: crmne/native-packages/.github/actions/attest@v0.7.0
+    with:
+      subject-path: dist/*.tar.gz
+```
+
+`subject-path` accepts a glob or newline-separated list. The composite action
+runs inside the calling job, preserving the application's build identity.
+It uses GitHub's pinned `actions/attest` implementation and needs no publisher
+key. It exposes `bundle-path` and `attestation-url` outputs. Each platform job
+attests its own final artifacts. A packaging-only job can attest the package it
+made, but that does not establish provenance for an earlier executable build.
+
+Consumers can verify a file with:
+
+```sh
+gh attestation verify FILE --repo OWNER/APP
+```
+
+For tighter policy, also constrain `--signer-workflow` and `--source-digest`.
+See [GitHub's artifact attestation documentation](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations).
+
+## Sign in the approved publication job
+
+After every build passes, download the final artifacts into a flat directory in
+a fresh signing job. Set its `environment: release-signing` in the app workflow
+and install Ruby 3.2 or later with Ed25519-capable OpenSSL before the signing
+step. Then call:
+
+```yaml
+- uses: crmne/native-packages/.github/actions/sign-release@v0.7.0
+  with:
+    directory: dist/release
+    public-key: assets/update-public-key.hex
+  env:
+    NATIVE_PACKAGES_SIGNING_KEY: ${{ secrets.UPDATE_SIGNING_KEY }}
+```
+
+The action uses the CLI from its own pinned source commit. It neither installs
+the gem nor runs project hooks, builds, tags, publishes or approves deployments.
+The caller checks out its committed public key and owns the publication step.
+For an existing secret variable name, set the action's `key-env` input.
+The action requires a fresh directory without an old checksum/signature pair.
+
+## Updater integration and key changes
+
+Embed the public key in the app. Reject missing or invalid signatures before
+accepting a checksum or downloading a package. Bind checksums to exact
+version/platform filenames, reject downgrade/replay updates, and retain package
+size checks, installation acknowledgement and rollback.
+
+The initial signature-enforcing version needs a trusted installation. Old
+hash-only clients are not protected until upgraded. Changing the key requires a
+tested compatibility transition in each app; the single-signature format here
+does not provide automatic key rotation. If a key is lost or compromised, stop
+automatic publication, revoke the secret and use an independently verified
+recovery installer. Do not replace an updater's trusted key from unsigned data.