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.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +1 -1
- data/README.md +5 -2
- data/docs/_guides/building-packages.md +5 -0
- data/docs/_guides/distribution-recipes.md +3 -1
- data/docs/_guides/getting-started.md +2 -2
- data/docs/_guides/github-actions.md +6 -4
- data/docs/_guides/hosted-repositories.md +170 -0
- data/docs/_guides/multi-platform.md +1 -1
- data/docs/_guides/native-recipes.md +6 -2
- data/docs/_guides/omarchy.md +131 -0
- data/docs/_guides/prereleases.md +1 -1
- data/docs/_guides/publishing.md +19 -0
- data/docs/_guides/release-signing.md +4 -4
- data/docs/_guides/windows-signing.md +259 -0
- data/docs/_reference/commands.md +32 -3
- data/docs/_reference/configuration.md +33 -3
- data/docs/_reference/platforms.md +126 -8
- data/docs/_reference/troubleshooting.md +22 -2
- data/docs/index.md +1 -1
- data/docs/releasing.md +2 -2
- data/examples/native-packages-all-formats.yaml +1 -1
- data/examples/native-packages-linux-distribution.yaml +76 -0
- data/examples/native-packages.yaml +1 -1
- data/lib/native_packages/appimage.rb +4 -66
- data/lib/native_packages/apt_repository.rb +190 -0
- data/lib/native_packages/build.rb +59 -6
- data/lib/native_packages/cli.rb +19 -2
- data/lib/native_packages/configuration.rb +29 -2
- data/lib/native_packages/dnf_repository.rb +131 -0
- data/lib/native_packages/flatpak.rb +171 -0
- data/lib/native_packages/flatpak_repository.rb +63 -0
- data/lib/native_packages/hosted_repository.rb +73 -0
- data/lib/native_packages/inspection.rb +3 -2
- data/lib/native_packages/macos_signing.rb +20 -2
- data/lib/native_packages/omarchy.rb +140 -0
- data/lib/native_packages/openpgp.rb +114 -0
- data/lib/native_packages/snap.rb +166 -0
- data/lib/native_packages/staging.rb +74 -0
- data/lib/native_packages/support.rb +1 -1
- data/lib/native_packages/windows_signing.rb +284 -0
- metadata +15 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b0bd80674a1e85d0ea267ea482d110043051ad942fbb8e0b618b3acaf3cb16eb
|
|
4
|
+
data.tar.gz: 05c74949fd067cf2b8b81adf7ac8a148a16c2620c5b9fdf4dea0af78f02457c6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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:
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
@@ -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.
|
|
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
|
|
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`.
|
data/docs/_guides/prereleases.md
CHANGED
data/docs/_guides/publishing.md
CHANGED
|
@@ -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:
|
|
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.
|
|
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.
|
|
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.
|
|
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
|