native-packages 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/CONTRIBUTING.md +1 -1
  3. data/README.md +5 -2
  4. data/docs/_guides/building-packages.md +5 -0
  5. data/docs/_guides/distribution-recipes.md +3 -1
  6. data/docs/_guides/getting-started.md +2 -2
  7. data/docs/_guides/github-actions.md +6 -4
  8. data/docs/_guides/hosted-repositories.md +170 -0
  9. data/docs/_guides/multi-platform.md +1 -1
  10. data/docs/_guides/native-recipes.md +6 -2
  11. data/docs/_guides/omarchy.md +131 -0
  12. data/docs/_guides/prereleases.md +1 -1
  13. data/docs/_guides/publishing.md +19 -0
  14. data/docs/_guides/release-signing.md +4 -4
  15. data/docs/_guides/windows-signing.md +259 -0
  16. data/docs/_reference/commands.md +32 -3
  17. data/docs/_reference/configuration.md +33 -3
  18. data/docs/_reference/platforms.md +126 -8
  19. data/docs/_reference/troubleshooting.md +22 -2
  20. data/docs/index.md +1 -1
  21. data/docs/releasing.md +2 -2
  22. data/examples/native-packages-all-formats.yaml +1 -1
  23. data/examples/native-packages-linux-distribution.yaml +76 -0
  24. data/examples/native-packages.yaml +1 -1
  25. data/lib/native_packages/appimage.rb +4 -66
  26. data/lib/native_packages/apt_repository.rb +190 -0
  27. data/lib/native_packages/build.rb +59 -6
  28. data/lib/native_packages/cli.rb +19 -2
  29. data/lib/native_packages/configuration.rb +29 -2
  30. data/lib/native_packages/dnf_repository.rb +131 -0
  31. data/lib/native_packages/flatpak.rb +171 -0
  32. data/lib/native_packages/flatpak_repository.rb +63 -0
  33. data/lib/native_packages/hosted_repository.rb +73 -0
  34. data/lib/native_packages/inspection.rb +3 -2
  35. data/lib/native_packages/macos_signing.rb +20 -2
  36. data/lib/native_packages/omarchy.rb +140 -0
  37. data/lib/native_packages/openpgp.rb +114 -0
  38. data/lib/native_packages/snap.rb +166 -0
  39. data/lib/native_packages/staging.rb +74 -0
  40. data/lib/native_packages/support.rb +1 -1
  41. data/lib/native_packages/windows_signing.rb +284 -0
  42. metadata +15 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 7991d9fd47977d5eda80c98ee460ef7c401b4db6eae41a74d285c58576bbb089
4
- data.tar.gz: 943a2ff5686edd0cfaa7f09fd9a213d797f4a628cf5eff9331127f84840c06c8
3
+ metadata.gz: b0bd80674a1e85d0ea267ea482d110043051ad942fbb8e0b618b3acaf3cb16eb
4
+ data.tar.gz: 05c74949fd067cf2b8b81adf7ac8a148a16c2620c5b9fdf4dea0af78f02457c6
5
5
  SHA512:
6
- metadata.gz: 2ac16d8c7b639da77db270af088839ab3e6ecbb6b913086208f26dc95db69b843df11c887ad556c744f493b5fe8ea85660095b9a5eff8425821daabb7b850330
7
- data.tar.gz: '094cba93dda2a8dbb0442d3b88d0efe5039ec28f715fdd85763e6dcdd56fde1b2a013813fbcf514930240dc874b31fcc562381c304c8e710a303e3bbe1d1e255'
6
+ metadata.gz: 8d8301d54fa95ee34b3c80ab34657b44cd1e2a09d751039d97e437115537ae5224bc4a42f936becd4cb5e6c42e4594f54af4adc925d6b5a4e74c07693bc5e3ea
7
+ data.tar.gz: 64d8dfa8a953385b61f4a12377fdf810b497571c28f859ab11615995f2093193e128650735a304771f2235a5f287a06aeb0c6e3790ed2232715d351fbce25a2c
data/CONTRIBUTING.md CHANGED
@@ -18,7 +18,7 @@ To check the packaged gem and standalone command:
18
18
 
19
19
  ```sh
20
20
  gem build native-packages.gemspec
21
- ruby test/gem_install.rb native-packages-0.10.0.gem
21
+ ruby test/gem_install.rb native-packages-0.12.0.gem
22
22
  ```
23
23
 
24
24
  See [Releasing the gem](docs/releasing.md) for publication and
data/README.md CHANGED
@@ -50,9 +50,9 @@ record. Local builds work without a GitHub release or credentials.
50
50
 
51
51
  | Platform | Outputs |
52
52
  | --- | --- |
53
- | Linux | DEB, RPM, AppImage, Arch Linux packages, Alpine APK, IPK, and source RPM |
53
+ | Linux | DEB, RPM, AppImage, Flatpak bundles, snaps, Arch Linux packages, Alpine APK, IPK, and source RPM |
54
54
  | macOS | DMG, using your packaging script; optional Apple signing and notarization |
55
- | Windows | MSIX, or MSI and Inno Setup installers using your packaging script |
55
+ | Windows | MSIX, or MSI and Inno Setup installers using your packaging script; optional Azure Artifact Signing |
56
56
 
57
57
  Each target needs files built for that platform. DMG builds run on macOS;
58
58
  MSI and Inno builds run on Windows. See [supported platforms](docs/_reference/platforms.md)
@@ -67,8 +67,11 @@ Start with [getting started](docs/_guides/getting-started.md).
67
67
  - [GitHub Actions](docs/_guides/github-actions.md) — add packaging to your release workflow.
68
68
  - [macOS and Windows installers](docs/_guides/native-recipes.md) — connect your native packaging scripts.
69
69
  - [Apple signing and notarization](docs/_guides/apple-notarization.md) — prepare macOS downloads for distribution.
70
+ - [Windows code signing](docs/_guides/windows-signing.md): sign Windows executables and installers with Azure Artifact Signing.
70
71
  - [Release signatures and attestations](docs/_guides/release-signing.md): authorize updater downloads and identify their build workflow.
72
+ - [Hosted package repositories](docs/_guides/hosted-repositories.md): publish signed repositories that users update through their package manager.
71
73
  - [AUR, Homebrew, and other repositories](docs/_guides/distribution-recipes.md) — generate and publish recipes.
74
+ - [Omarchy packages](docs/_guides/omarchy.md): write a first Omarchy recipe that Omarchy's bot then keeps updated.
72
75
 
73
76
  For a particular option or error, see the [configuration reference](docs/_reference/configuration.md),
74
77
  [command reference](docs/_reference/commands.md), and [troubleshooting guide](docs/_reference/troubleshooting.md).
@@ -130,6 +130,11 @@ Add `appimage` to a Linux target's formats for a single file that runs without
130
130
  installation. It needs one desktop entry and its icon among the contents; see
131
131
  [AppImage](../_reference/platforms.md#appimage).
132
132
 
133
+ Add `flatpak` for a Flatpak bundle of the same files, with a top-level
134
+ `flatpak` section naming the app ID, runtime and sandbox permissions; see
135
+ [Flatpak](../_reference/platforms.md#flatpak). Add `snap` for a snap, with a
136
+ top-level `snap` section; see [Snap](../_reference/platforms.md#snap).
137
+
133
138
  Use a separate musl or static build for Alpine. Changing `formats` alone
134
139
  does not change which systems a binary can run on.
135
140
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: Distribution recipes
3
3
  description: Generate AUR and Homebrew recipes with release checksums, review downstream changes, and publish repository updates.
4
- nav_order: 7
4
+ nav_order: 8
5
5
  ---
6
6
 
7
7
  # Distribution recipes
@@ -189,4 +189,6 @@ process. The CLI reports those instructions rather than submitting an update.
189
189
  Once the process is tested, enable destination publication in
190
190
  [GitHub Actions](github-actions.md#enable-aur-or-homebrew-publication).
191
191
  For package files themselves, use [Publishing a release](publishing.md).
192
+ To ship your AUR binary recipe in Omarchy's repository as well, see
193
+ [Omarchy packages](omarchy.md).
192
194
  This tool does not host APT or DNF package indexes.
@@ -17,7 +17,7 @@ own compiled executable, or build the tiny example below.
17
17
  You need Ruby 3.2 or later. Install the version used by these guides:
18
18
 
19
19
  ```sh
20
- gem install native-packages --version 0.10.0
20
+ gem install native-packages --version 0.12.0
21
21
  ```
22
22
 
23
23
  For Linux packages, install **nFPM 2.47.0**, the helper native-packages uses to
@@ -79,7 +79,7 @@ Open the generated `native-packages.yaml` and replace its contents with:
79
79
  ```yaml
80
80
  schema: 1
81
81
  tool:
82
- version: '0.10.0'
82
+ version: '0.12.0'
83
83
  nfpm: '2.47.0'
84
84
 
85
85
  nfpm:
@@ -24,7 +24,7 @@ packaging:
24
24
  needs: release
25
25
  permissions:
26
26
  contents: write
27
- uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
27
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
28
28
  with:
29
29
  version: ${{ github.ref_name }}
30
30
  publish: true
@@ -39,7 +39,7 @@ The configuration must include `release.repository` and a `release_asset`
39
39
  for each selected target. See [Publishing a release](publishing.md).
40
40
 
41
41
  Use the same native-packages release for the workflow and `tool.version`.
42
- For an immutable workflow reference, replace `v0.10.0` with that release's
42
+ For an immutable workflow reference, replace `v0.12.0` with that release's
43
43
  full commit SHA.
44
44
 
45
45
  ## Build without publishing
@@ -57,7 +57,7 @@ permissions:
57
57
  contents: read
58
58
  jobs:
59
59
  packaging:
60
- uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
60
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
61
61
  ```
62
62
 
63
63
  Validation does not compile the app or check that future release inputs exist.
@@ -72,7 +72,7 @@ packaging:
72
72
  needs: build
73
73
  permissions:
74
74
  contents: write
75
- uses: crmne/native-packages/.github/workflows/package.yml@v0.10.0
75
+ uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
76
76
  with:
77
77
  version: '1.2.3'
78
78
  source-artifact: linux-binaries
@@ -102,6 +102,8 @@ It requires every format declared for those targets. An empty selection
102
102
  means all configured targets.
103
103
 
104
104
  Build DMG, MSI and Inno targets in your own macOS and Windows jobs with the CLI.
105
+ Those jobs can [sign and notarize for Apple](apple-notarization.md) and
106
+ [sign for Windows](windows-signing.md).
105
107
  See [Building across platforms](multi-platform.md) for combining their outputs
106
108
  and generating recipes after all packages are available.
107
109
 
@@ -0,0 +1,170 @@
1
+ ---
2
+ title: Hosted package repositories
3
+ description: Publish signed APT, DNF and Flatpak repositories that users add once and update with their package manager.
4
+ nav_order: 13
5
+ ---
6
+
7
+ # Hosted package repositories
8
+
9
+ A package attached to a GitHub release is installed once and then forgotten.
10
+ Users who add your repository instead get every update through their own
11
+ package manager. native-packages writes these repositories as static files
12
+ into a directory you choose, such as a checkout of a GitHub Pages site, and
13
+ signs them with your OpenPGP key. It only writes files: your release job
14
+ commits and pushes the directory afterwards, as it would any website change.
15
+
16
+ ## 1. Make a signing key
17
+
18
+ Use a key for this repository alone, without an expiry date you might miss,
19
+ and keep its secret half out of every repository:
20
+
21
+ ```sh
22
+ gpg --quick-gen-key 'Hello packages <packages@example.org>' ed25519 sign never
23
+ gpg --list-keys --with-colons packages@example.org | awk -F: '/^fpr/ { print $10; exit }'
24
+ ```
25
+
26
+ The second command prints the key's full fingerprint, which goes into the
27
+ configuration. Locally, native-packages signs with the key your GnuPG agent
28
+ already holds. In CI, export the secret key and store it as a secret:
29
+
30
+ ```sh
31
+ gpg --armor --export-secret-keys FINGERPRINT
32
+ ```
33
+
34
+ Pass it to the publish step as `NATIVE_PACKAGES_GPG_KEY`, and the key's
35
+ passphrase, if it has one, as `NATIVE_PACKAGES_GPG_PASSPHRASE`.
36
+ native-packages removes both from its environment before running any other
37
+ program, imports the key into a temporary keyring that it deletes
38
+ afterwards, and checks every signature against the configured fingerprint
39
+ before writing it.
40
+
41
+ ## 2. Configure the repositories
42
+
43
+ ```yaml
44
+ apt:
45
+ directory: ../hello-site/apt
46
+ url: https://example.org/apt
47
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
48
+ keep: 3
49
+ dnf:
50
+ directory: ../hello-site/rpm
51
+ url: https://example.org/rpm
52
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
53
+ flatpak:
54
+ # The app's id, runtime, command and permissions, as for any Flatpak.
55
+ repository:
56
+ directory: ../hello-site/flatpak
57
+ url: https://example.org/flatpak
58
+ title: Hello
59
+ signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
60
+ ```
61
+
62
+ | Field | Purpose |
63
+ | --- | --- |
64
+ | `directory` | Required. Where the repository is written, relative to the configuration file. |
65
+ | `url` | Required. The `https://` URL at which that directory is served. |
66
+ | `signing_key` | Required. The signing key's full fingerprint. |
67
+ | `keep` | APT and DNF only. How many versions of each package and architecture to keep. Defaults to `3`. |
68
+ | `suite`, `component` | APT only. Default to `stable` and `main`. |
69
+ | `title`, `homepage` | Flatpak only. The repository's name in software centers (defaults to the package name) and an `https://` homepage. |
70
+
71
+ ## 3. Publish
72
+
73
+ Build as usual, then publish the build to the repositories:
74
+
75
+ ```sh
76
+ native-packages build --version 1.2.3
77
+ native-packages publish --from dist/packages/1.2.3 --to github,apt,dnf,flatpak
78
+ ```
79
+
80
+ Each publication adds the build's packages to what the directory already
81
+ holds, removes versions beyond `keep`, and rewrites and signs the indexes. A
82
+ file that is already published can only be published again unchanged. Then
83
+ commit and push the directory.
84
+
85
+ ## APT
86
+
87
+ `publish --to apt` copies each `.deb` into `pool/main/h/hello/` and writes
88
+ `dists/stable/` with `Packages` and `Packages.gz` for every architecture,
89
+ `Release`, a clearsigned `InRelease` and a detached `Release.gpg`. These are
90
+ written by native-packages itself, so no Debian tools are needed. Beside them
91
+ go the public key as `hello.gpg` and a `hello.sources` file. Users install
92
+ with:
93
+
94
+ ```sh
95
+ sudo install -d -m 0755 /etc/apt/keyrings
96
+ sudo curl -fsSLo /etc/apt/keyrings/hello.gpg https://example.org/apt/hello.gpg
97
+ sudo curl -fsSLo /etc/apt/sources.list.d/hello.sources https://example.org/apt/hello.sources
98
+ sudo apt update && sudo apt install hello
99
+ ```
100
+
101
+ The `.sources` file trusts this key for this repository alone. Use it on
102
+ apt 1.1 and later (Debian 9, Ubuntu 16.04 and newer).
103
+
104
+ ## DNF
105
+
106
+ `publish --to dnf` copies each `.rpm` into `packages/`, runs `createrepo_c`
107
+ to write `repodata/`, and signs `repodata/repomd.xml` as
108
+ `repodata/repomd.xml.asc`. Beside them go the public key as `hello.asc` and
109
+ a `hello.repo` file. Users install with:
110
+
111
+ ```sh
112
+ sudo curl -fsSLo /etc/yum.repos.d/hello.repo https://example.org/rpm/hello.repo
113
+ sudo dnf install hello
114
+ ```
115
+
116
+ dnf asks once whether to trust the key, then checks the metadata's signature
117
+ on every update (`repo_gpgcheck=1`). The packages themselves are signed only
118
+ if you sign them, with nFPM's `rpm.signature`; `hello.repo` turns on
119
+ `gpgcheck` when every published RPM carries a signature. The same file works
120
+ for Zypper (`zypper addrepo https://example.org/rpm/hello.repo`). Install
121
+ `createrepo_c` (in the `createrepo-c` package on Debian and Ubuntu) on the
122
+ machine that publishes.
123
+
124
+ ## Flatpak
125
+
126
+ `publish --to flatpak` imports each Flatpak bundle into an OSTree
127
+ repository in the directory, signing its commits, then updates the
128
+ repository's summary and static deltas with `flatpak build-update-repo`.
129
+ Each bundle's commit stands alone, without the previous version as its
130
+ parent, so the repository serves each app's newest commit and prunes the
131
+ rest; users cannot roll back to an older version through it. Beside it go
132
+ `hello.flatpakrepo`, for adding the repository, and `ID.flatpakref`, for
133
+ installing the app, both carrying the public key. Users install with:
134
+
135
+ ```sh
136
+ flatpak install --user https://example.org/flatpak/org.example.Hello.flatpakref
137
+ ```
138
+
139
+ and get updates from `flatpak update`. If `flatpak.runtime_repo` is set, a
140
+ missing runtime comes from there. Publishing needs `flatpak` and `ostree`.
141
+
142
+ This is your own repository, not Flathub. native-packages does not write or
143
+ submit Flathub manifests, because Flathub does not accept AI-assisted
144
+ manifests or submissions.
145
+
146
+ ## GitHub Pages
147
+
148
+ Serve the site from a branch or folder, and add an empty `.nojekyll` file
149
+ at its root so GitHub publishes the repository's files as they are. A
150
+ release job can check out the site beside the app:
151
+
152
+ ```yaml
153
+ - uses: actions/checkout@v7
154
+ with:
155
+ repository: example/hello-site
156
+ path: hello-site
157
+ token: ${{ secrets.SITE_TOKEN }}
158
+ - run: native-packages publish --from dist/native-packages --to apt,dnf,flatpak
159
+ env:
160
+ NATIVE_PACKAGES_GPG_KEY: ${{ secrets.PACKAGES_GPG_KEY }}
161
+ - run: |
162
+ cd hello-site
163
+ git add -A
164
+ git commit -m "Publish hello $VERSION"
165
+ git push
166
+ ```
167
+
168
+ With directories such as `hello-site/apt` in the configuration, the
169
+ repositories land in that checkout. GitHub Pages serves sites of up to 1 GB, so keep `keep` low
170
+ for large packages.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: Building across platforms
3
3
  description: Build targets on their required hosts, combine the results, and generate distribution recipes once all packages are ready.
4
- nav_order: 8
4
+ nav_order: 10
5
5
  ---
6
6
 
7
7
  # Building across platforms
@@ -31,7 +31,7 @@ Here is a complete configuration for an ARM64 Mac app and an x86-64 Windows app:
31
31
  ```yaml
32
32
  schema: 1
33
33
  tool:
34
- version: '0.10.0'
34
+ version: '0.12.0'
35
35
  nfpm: '2.47.0'
36
36
  nfpm:
37
37
  name: hello
@@ -213,7 +213,11 @@ For DMG targets, providing complete Apple credentials enables automatic input
213
213
  signing and DMG notarization. Follow [Apple signing and notarization](apple-notarization.md).
214
214
  The DMG script must preserve the signed app when copying it into the image.
215
215
 
216
- For Windows, use an `after_package` hook to sign the output:
216
+ For MSI and Inno targets, a `windows.signing` section and Azure Artifact
217
+ Signing settings enable automatic signing of the input's code and of the
218
+ installer. Follow [Windows code signing](windows-signing.md).
219
+
220
+ To sign with another tool, use an `after_package` hook:
217
221
 
218
222
  ```yaml
219
223
  after_package: [pwsh, -File, packaging/sign.ps1, '@PACKAGE@']
@@ -0,0 +1,131 @@
1
+ ---
2
+ title: Omarchy packages
3
+ description: Turn your AUR binary recipe into an Omarchy package that Omarchy's bot updates after every GitHub release.
4
+ nav_order: 9
5
+ ---
6
+
7
+ # Omarchy packages
8
+
9
+ [Omarchy](https://omarchy.org) installs packages from its own repository,
10
+ `https://pkgs.omarchy.org`, built from recipes in
11
+ [omacom/omarchy-pkgs](https://github.com/omacom/omarchy-pkgs). A recipe is a
12
+ `PKGBUILD` plus `.omarchy/package.json`. When that file declares where your
13
+ releases come from, Omarchy's bot opens and merges every later version update
14
+ itself. You send one pull request, once.
15
+
16
+ `omarchy-recipe` writes that first recipe from your existing AUR `-bin`
17
+ template. It adds to the AUR; keep publishing there as before.
18
+
19
+ ## Before you start
20
+
21
+ You need:
22
+
23
+ - an AUR binary recipe template, mapped as `arch/NAME-bin/PKGBUILD` under
24
+ `templates`, that downloads each architecture's release archive with
25
+ `source_x86_64` and `source_aarch64`
26
+ (see [Distribution recipes](distribution-recipes.md));
27
+ - a published, stable GitHub release tagged `vX.Y.Z` whose checksum manifest
28
+ (`release.checksums`, `checksums.txt` by default) lists those archives;
29
+ - Docker or Podman, to build the package with Omarchy's own tooling.
30
+
31
+ ## 1. Write the recipe
32
+
33
+ Fork [omacom/omarchy-pkgs](https://github.com/omacom/omarchy-pkgs), clone your
34
+ fork, and branch from `master`. Then, from your app's directory:
35
+
36
+ ```sh
37
+ native-packages omarchy-recipe ../omarchy-pkgs --release v1.2.3
38
+ ```
39
+
40
+ It renders the templates under `arch/NAME-bin/` for that release into
41
+ `pkgbuilds/NAME-bin/`, with `pkgrel=1` and the checksums from the release's
42
+ manifest. Pass `--package NAME-bin` when you have more than one `-bin`
43
+ template. It refuses a recipe directory that already exists: after the first
44
+ pull request the recipe is Omarchy's, and the bot maintains it.
45
+
46
+ The bot only rewrites `pkgver`, `pkgrel` and the checksums, so every source URL
47
+ has to follow `pkgver`. A URL your AUR template wrote out in full, such as
48
+ `@AMD64_URL@`, is rewritten to use `${pkgver}`. The command then checks the
49
+ recipe by setting another version and confirming every URL moves with it, and
50
+ stops if one does not, for example when a URL uses its own version variable or
51
+ single quotes.
52
+
53
+ Next to the `PKGBUILD` it writes `.omarchy/package.json`:
54
+
55
+ ```json
56
+ {
57
+ "source": "local",
58
+ "auto_merge": true,
59
+ "release_ring": "fast",
60
+ "min_release_age": "24h",
61
+ "upstream": {
62
+ "watch": {
63
+ "github": "your-name/hello",
64
+ "pattern": "v(?P<version>[0-9]+(?:\\.[0-9]+)*)"
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ | Field | Meaning |
71
+ | --- | --- |
72
+ | `upstream.watch` | Where releases come from: your GitHub repository's releases, with a `pattern` that must match the whole tag. For a new release the bot sets `pkgver`, so the source URLs move with it, and takes each archive's SHA-256 from the digest GitHub reports for that release asset, without downloading it. |
73
+ | `auto_merge` | Updates go through Omarchy's hourly tracker instead of the six-hourly reviewed sync, and merge themselves once the build checks pass. |
74
+ | `min_release_age` | The bot waits until a release is this old (`24h`) before proposing it, so you have a day to pull a bad release. It then takes the newest release that has cleared the window. |
75
+ | `release_ring` | `fast` publishes each merge to Omarchy's `edge`, `rc` and `stable` channels at once, not only `edge`. It suits prebuilt binaries and static tools, which do not depend on the exact Arch snapshot. Omarchy's CI checks each fast-ring build on every channel and fails it when a library or symbol is missing there. |
76
+
77
+ Omarchy uses the same settings for
78
+ [superwhisper-bin](https://github.com/omacom/omarchy-pkgs/tree/master/pkgbuilds/superwhisper-bin).
79
+ Edit them before you send the pull request if your app needs otherwise: drop
80
+ `release_ring` for an app that must be rebuilt when its libraries change, or
81
+ `auto_merge` to have a maintainer review every update.
82
+
83
+ ## 2. Check and build it
84
+
85
+ From the omarchy-pkgs checkout:
86
+
87
+ ```sh
88
+ tests/pinned-sources.sh
89
+ bin/build --package hello-bin
90
+ sudo pacman -U build-output/edge/x86_64/hello-bin-1.2.3-1-x86_64.pkg.tar.zst
91
+ ```
92
+
93
+ `bin/build` builds in Omarchy's builder container, as CI does. With Docker it
94
+ calls `sudo` once to fix the ownership of its output.
95
+
96
+ Check that the watch finds your current release:
97
+
98
+ ```sh
99
+ python helpers/upstream-watch.py check pkgbuilds/hello-bin
100
+ ```
101
+
102
+ On a current recipe it prints `"status": "skipped"` with `"reason": "already current"`.
103
+ To see the bot update the recipe, copy the checkout, set an older `pkgver` and
104
+ wrong hashes in the copy, and run `bin/sync-upstream hello-bin` there: it should
105
+ move the recipe to the newest release older than `min_release_age`, with the
106
+ hashes your manifest lists.
107
+
108
+ ## 3. Send the first pull request
109
+
110
+ Commit only `pkgbuilds/hello-bin/` and open a pull request against `master`
111
+ with that one package. Say what the app is, that you maintain it upstream,
112
+ which checks you ran, and that its updates come from the `upstream`
113
+ declaration.
114
+
115
+ Omarchy builds pull requests only for trusted authors. Unless you are a
116
+ collaborator or listed in the repository's `.github/VOUCHED.td`, the pull
117
+ request shows **Awaiting build approval** (on your first one, GitHub's
118
+ "workflows awaiting approval") until a maintainer adds the `build-approved`
119
+ label. Then CI builds `x86_64` and `aarch64`, the pull request merges itself
120
+ once `result`, `self-tests` and `build-isolation` pass, and the package is
121
+ published within minutes.
122
+
123
+ ## After it merges
124
+
125
+ Publish releases as usual. After each GitHub release, once it has cleared
126
+ `min_release_age`, the bot opens an update, builds it and merges it. Keep the
127
+ `vX.Y.Z` tags and the archive names stable: a renamed asset stops the updates
128
+ until the recipe is fixed.
129
+
130
+ For a packaging change at the same version, such as a new dependency, send a
131
+ pull request that edits the recipe and bumps `pkgrel`.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: Prereleases
3
3
  description: Build and publish alpha, beta, and release candidate packages with explicit version rules.
4
- nav_order: 9
4
+ nav_order: 11
5
5
  ---
6
6
 
7
7
  # Prereleases
@@ -115,6 +115,25 @@ To combine builds from several jobs, follow
115
115
  [Building across platforms](multi-platform.md). Builds with deferred recipes
116
116
  must be finalized before publication.
117
117
 
118
+ ## Upload snaps to the Snap Store
119
+
120
+ Register the snap's name in the Snap Store, set `snap.store.channels`, and
121
+ export a login for the release job:
122
+
123
+ ```sh
124
+ snapcraft export-login --snaps hello --acls package_upload,package_release credentials.txt
125
+ ```
126
+
127
+ Store that file's contents as a secret and pass it to the publish step as
128
+ `SNAPCRAFT_STORE_CREDENTIALS`. With `snapcraft` installed:
129
+
130
+ ```sh
131
+ native-packages publish --from dist/packages/1.2.3 --to snapcraft
132
+ ```
133
+
134
+ Each snap in the build is uploaded and released to the configured channels.
135
+ See [Snap](../_reference/platforms.md#snap).
136
+
118
137
  ## Update distribution recipes
119
138
 
120
139
  For AUR, Homebrew, or another downstream repository, first configure its
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: Release signatures and attestations
3
3
  description: Share release signing machinery while keeping application keys, approval policy and build identity separate.
4
- nav_order: 10
4
+ nav_order: 12
5
5
  ---
6
6
 
7
7
  # Release signatures and attestations
@@ -67,7 +67,7 @@ Package publication's separate `packaging-checksums.txt` is also unchanged.
67
67
 
68
68
  ## Attest in the application's build job
69
69
 
70
- The examples use `v0.10.0` for readability. For release workflows, replace it
70
+ The examples use `v0.12.0` for readability. For release workflows, replace it
71
71
  with that release's reviewed full commit SHA, not a mutable branch.
72
72
  After producing the final package, before uploading it, add this step to the
73
73
  job that built it:
@@ -79,7 +79,7 @@ permissions:
79
79
  attestations: write
80
80
  steps:
81
81
  # Existing checkout, build, platform signing and packaging steps go here.
82
- - uses: crmne/native-packages/.github/actions/attest@v0.10.0
82
+ - uses: crmne/native-packages/.github/actions/attest@v0.12.0
83
83
  with:
84
84
  subject-path: dist/*.tar.gz
85
85
  ```
@@ -108,7 +108,7 @@ and install Ruby 3.2 or later with Ed25519-capable OpenSSL before the signing
108
108
  step. Then call:
109
109
 
110
110
  ```yaml
111
- - uses: crmne/native-packages/.github/actions/sign-release@v0.10.0
111
+ - uses: crmne/native-packages/.github/actions/sign-release@v0.12.0
112
112
  with:
113
113
  directory: dist/release
114
114
  public-key: assets/update-public-key.hex