native-packages 0.10.0 → 0.11.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 +3 -1
- 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/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/release-signing.md +4 -4
- data/docs/_guides/windows-signing.md +259 -0
- data/docs/_reference/commands.md +29 -1
- data/docs/_reference/configuration.md +27 -1
- data/docs/_reference/platforms.md +4 -3
- data/docs/_reference/troubleshooting.md +22 -2
- data/docs/releasing.md +2 -2
- data/examples/native-packages-all-formats.yaml +1 -1
- data/examples/native-packages.yaml +1 -1
- data/lib/native_packages/build.rb +20 -4
- data/lib/native_packages/cli.rb +19 -2
- data/lib/native_packages/configuration.rb +3 -1
- data/lib/native_packages/omarchy.rb +140 -0
- data/lib/native_packages/support.rb +1 -1
- data/lib/native_packages/windows_signing.rb +284 -0
- metadata +5 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ac048cc41a4da6fce8d7fb71973cac33e9f8590eea8e78c0817d4a5edf09b78f
|
|
4
|
+
data.tar.gz: 04222cbfdc2f7fbf432506bf5d68d752a3bee15b158e95d42ec6ce70f869b039
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 569d551cc59851f81449c32d4e92afcc1729902fea9aa3cff7ce68ca88957ce996b29465ccfd255af9b598cb50de413b885d5189039d091e46174607e9a3fc0a
|
|
7
|
+
data.tar.gz: 0fcbae8d5b81e151f4fdbea78e29323f22220670fe0e6f28920512cb4355346c762f48e066b6f34e30576212ccc1d9ba81fafadaa05929333451c72e00903878
|
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.11.0.gem
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
See [Releasing the gem](docs/releasing.md) for publication and
|
data/README.md
CHANGED
|
@@ -52,7 +52,7 @@ record. Local builds work without a GitHub release or credentials.
|
|
|
52
52
|
| --- | --- |
|
|
53
53
|
| Linux | DEB, RPM, AppImage, 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,10 @@ 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.
|
|
71
72
|
- [AUR, Homebrew, and other repositories](docs/_guides/distribution-recipes.md) — generate and publish recipes.
|
|
73
|
+
- [Omarchy packages](docs/_guides/omarchy.md): write a first Omarchy recipe that Omarchy's bot then keeps updated.
|
|
72
74
|
|
|
73
75
|
For a particular option or error, see the [configuration reference](docs/_reference/configuration.md),
|
|
74
76
|
[command reference](docs/_reference/commands.md), and [troubleshooting guide](docs/_reference/troubleshooting.md).
|
|
@@ -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.11.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.11.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.11.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.11.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.11.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.11.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
|
|
|
@@ -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.11.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
|
@@ -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.11.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.11.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.11.0
|
|
112
112
|
with:
|
|
113
113
|
directory: dist/release
|
|
114
114
|
public-key: assets/update-public-key.hex
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Windows code signing
|
|
3
|
+
description: Sign Windows executables and installers with Azure Artifact Signing, from GitHub Actions through OIDC, with no stored secret.
|
|
4
|
+
nav_order: 7
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Windows code signing
|
|
8
|
+
|
|
9
|
+
native-packages can sign your Windows app with
|
|
10
|
+
[Azure Artifact Signing](https://learn.microsoft.com/azure/artifact-signing/)
|
|
11
|
+
(formerly Trusted Signing). It signs the executables and libraries that go
|
|
12
|
+
into your MSI or Inno Setup installer, then the installer itself, before
|
|
13
|
+
recording the package checksum. Every signature uses SHA-256 and Microsoft's
|
|
14
|
+
RFC 3161 timestamp, and is checked afterwards.
|
|
15
|
+
|
|
16
|
+
Signed downloads name your organization as the publisher in Windows' security
|
|
17
|
+
prompts. A signature does not silence SmartScreen at once: reputation builds as
|
|
18
|
+
people download releases signed by the same publisher, so keep signing every
|
|
19
|
+
release with the same certificate profile.
|
|
20
|
+
|
|
21
|
+
This guide assumes a working [MSI or Inno target](native-recipes.md). It also
|
|
22
|
+
covers files built outside native-packages, such as a portable ZIP's
|
|
23
|
+
executable or a setup program your workflow compiles itself.
|
|
24
|
+
|
|
25
|
+
## What you need
|
|
26
|
+
|
|
27
|
+
- An Azure subscription with an Artifact Signing account, and a **Public
|
|
28
|
+
Trust** certificate profile. Creating the profile needs Microsoft's identity
|
|
29
|
+
validation of your organization, which can take several business days.
|
|
30
|
+
- An x64 Windows machine or runner for signing, such as GitHub's
|
|
31
|
+
`windows-latest`. The signing tools are x64 builds; sign Arm64 apps on x64.
|
|
32
|
+
- No client secret and no certificate file: signing uses your Azure CLI
|
|
33
|
+
sign-in, which in GitHub Actions comes from an OIDC token.
|
|
34
|
+
|
|
35
|
+
## 1. Set up the account and an identity that may sign
|
|
36
|
+
|
|
37
|
+
In the Azure portal (or with Terraform or the Azure CLI):
|
|
38
|
+
|
|
39
|
+
1. Create an Artifact Signing account. Note its endpoint, which depends on
|
|
40
|
+
the region, such as `https://weu.codesigning.azure.net/` for West Europe.
|
|
41
|
+
2. Under **Identity validation**, request a Public Trust validation for your
|
|
42
|
+
organization and complete it.
|
|
43
|
+
3. Create a certificate profile of type **Public Trust** from that identity.
|
|
44
|
+
4. Create a Microsoft Entra app registration for your repository and give its
|
|
45
|
+
service principal the **Artifact Signing Certificate Profile Signer** role
|
|
46
|
+
on the account.
|
|
47
|
+
|
|
48
|
+
## 2. Trust your GitHub workflow, with the right subject
|
|
49
|
+
|
|
50
|
+
Add a federated credential to the app registration so that jobs in one GitHub
|
|
51
|
+
environment can sign in as it:
|
|
52
|
+
|
|
53
|
+
| Field | Value |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| Issuer | `https://token.actions.githubusercontent.com` |
|
|
56
|
+
| Audience | `api://AzureADTokenExchange` |
|
|
57
|
+
| Subject | The subject your repository's tokens carry, ending in `:environment:windows-signing` |
|
|
58
|
+
|
|
59
|
+
The subject must match the token character for character. Many repositories
|
|
60
|
+
now present GitHub's **immutable** subject, which names the owner and the
|
|
61
|
+
repository by their numeric IDs as well as their names:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
repo:OWNER@OWNER_ID/REPOSITORY@REPOSITORY_ID:environment:windows-signing
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
A credential with the familiar `repo:OWNER/REPOSITORY:environment:windows-signing`
|
|
68
|
+
then fails with `AADSTS700213: No matching federated identity record found`.
|
|
69
|
+
Read the prefix your repository uses and append the environment:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
gh api repos/OWNER/REPOSITORY/actions/oidc/customization/sub --jq .sub_claim_prefix
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
For example, `repo:crmne@106617/zapfast@1350713137` becomes the subject
|
|
76
|
+
`repo:crmne@106617/zapfast@1350713137:environment:windows-signing`. The
|
|
77
|
+
immutable form is also safer: a renamed or recreated repository cannot take
|
|
78
|
+
over the trust.
|
|
79
|
+
|
|
80
|
+
## 3. Create the GitHub environment
|
|
81
|
+
|
|
82
|
+
In your repository's **Settings → Environments**, create `windows-signing`.
|
|
83
|
+
Under **Deployment branches and tags**, allow only your release tags, such as
|
|
84
|
+
`v*`, so that only a release run can get a token. Add these environment
|
|
85
|
+
variables. None of them is secret:
|
|
86
|
+
|
|
87
|
+
| Variable | Value |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| `AZURE_CLIENT_ID` | The app registration's application (client) ID. |
|
|
90
|
+
| `AZURE_TENANT_ID` | Your Microsoft Entra tenant ID. |
|
|
91
|
+
| `AZURE_SUBSCRIPTION_ID` | The subscription holding the signing account. |
|
|
92
|
+
| `AZURE_SIGNING_ENDPOINT` | The account's endpoint, such as `https://weu.codesigning.azure.net/`. |
|
|
93
|
+
| `AZURE_SIGNING_ACCOUNT` | The Artifact Signing account name. |
|
|
94
|
+
| `AZURE_SIGNING_PROFILE` | The certificate profile name. |
|
|
95
|
+
|
|
96
|
+
With the GitHub CLI:
|
|
97
|
+
|
|
98
|
+
```sh
|
|
99
|
+
gh api -X PUT repos/OWNER/REPOSITORY/environments/windows-signing \
|
|
100
|
+
-F 'deployment_branch_policy[protected_branches]=false' \
|
|
101
|
+
-F 'deployment_branch_policy[custom_branch_policies]=true'
|
|
102
|
+
gh api -X POST repos/OWNER/REPOSITORY/environments/windows-signing/deployment-branch-policies \
|
|
103
|
+
-f name='v*' -f type=tag
|
|
104
|
+
echo https://weu.codesigning.azure.net/ | gh variable set AZURE_SIGNING_ENDPOINT -R OWNER/REPOSITORY -e windows-signing
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 4. Turn signing on in the configuration
|
|
108
|
+
|
|
109
|
+
```yaml
|
|
110
|
+
windows:
|
|
111
|
+
signing:
|
|
112
|
+
provider: azure-artifact-signing
|
|
113
|
+
description: Hello
|
|
114
|
+
description_url: https://example.org/hello
|
|
115
|
+
publisher: Example Ltd
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`provider` is required. `description` is the program name Windows shows when
|
|
119
|
+
an installer asks for permission; it defaults to the package name.
|
|
120
|
+
`description_url` defaults to `nfpm.homepage`. With `publisher`, every
|
|
121
|
+
signature must name exactly that organization, which catches a wrong
|
|
122
|
+
certificate profile before release.
|
|
123
|
+
|
|
124
|
+
The account itself comes from `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`
|
|
125
|
+
and `AZURE_SIGNING_PROFILE`, so the same configuration builds unsigned packages
|
|
126
|
+
locally and in pull requests. With none of them set, builds stay unsigned. With
|
|
127
|
+
all three, signing is automatic. An incomplete set fails with the names of the
|
|
128
|
+
missing variables.
|
|
129
|
+
|
|
130
|
+
## 5. Sign in the release workflow
|
|
131
|
+
|
|
132
|
+
The Windows job enters the environment, signs in with
|
|
133
|
+
[`azure/login`](https://github.com/Azure/login), and passes the environment's
|
|
134
|
+
variables to native-packages:
|
|
135
|
+
|
|
136
|
+
```yaml
|
|
137
|
+
jobs:
|
|
138
|
+
windows:
|
|
139
|
+
runs-on: windows-latest
|
|
140
|
+
environment: windows-signing
|
|
141
|
+
permissions:
|
|
142
|
+
contents: read
|
|
143
|
+
id-token: write
|
|
144
|
+
env:
|
|
145
|
+
AZURE_SIGNING_ENDPOINT: ${{ vars.AZURE_SIGNING_ENDPOINT }}
|
|
146
|
+
AZURE_SIGNING_ACCOUNT: ${{ vars.AZURE_SIGNING_ACCOUNT }}
|
|
147
|
+
AZURE_SIGNING_PROFILE: ${{ vars.AZURE_SIGNING_PROFILE }}
|
|
148
|
+
steps:
|
|
149
|
+
- uses: actions/checkout@v4
|
|
150
|
+
- uses: ruby/setup-ruby@v1
|
|
151
|
+
with:
|
|
152
|
+
ruby-version: '4.0'
|
|
153
|
+
- run: gem install native-packages --version 0.11.0 --no-document
|
|
154
|
+
- run: cargo build --locked --release --target x86_64-pc-windows-msvc
|
|
155
|
+
- name: Sign in to Azure for code signing
|
|
156
|
+
if: vars.AZURE_SIGNING_PROFILE != ''
|
|
157
|
+
uses: azure/login@a641126d1b8aa4d1fa005f4f92df94a3a4c4c906 # v3.1.0
|
|
158
|
+
with:
|
|
159
|
+
client-id: ${{ vars.AZURE_CLIENT_ID }}
|
|
160
|
+
tenant-id: ${{ vars.AZURE_TENANT_ID }}
|
|
161
|
+
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
|
|
162
|
+
# Sign before anything packs the executable, so the ZIP, the setup
|
|
163
|
+
# program and the MSI all carry a signed copy.
|
|
164
|
+
- if: vars.AZURE_SIGNING_PROFILE != ''
|
|
165
|
+
run: native-packages sign-windows target/x86_64-pc-windows-msvc/release/hello.exe
|
|
166
|
+
# ... build the portable ZIP and copy the app into the MSI input ...
|
|
167
|
+
- run: native-packages build --version 1.2.3 --target windows-amd64 --output dist/windows-packages
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`native-packages build` signs the MSI or Inno installer of every Windows
|
|
171
|
+
native target. Sign anything else your workflow makes, such as a setup program
|
|
172
|
+
it compiles itself, with `sign-windows` before attesting and uploading it:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
native-packages sign-windows dist/hello-v1.2.3-setup.exe
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The `if:` conditions skip the sign-in and `sign-windows` outside the
|
|
179
|
+
environment, where its variables are empty; `build` then leaves the installer
|
|
180
|
+
unsigned. Release workflows often run on more than tags. To keep other runs
|
|
181
|
+
unsigned, enter the environment only on tag pushes:
|
|
182
|
+
|
|
183
|
+
```yaml
|
|
184
|
+
environment: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && 'windows-signing' || '' }}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## What the build does
|
|
188
|
+
|
|
189
|
+
For a Windows MSI or Inno target with signing on, `native-packages build`:
|
|
190
|
+
|
|
191
|
+
1. Copies and checks your prepared input.
|
|
192
|
+
2. Signs every executable and library in the copy that has no valid
|
|
193
|
+
signature yet. Code that is already signed, by `sign-windows` or by its
|
|
194
|
+
vendor, keeps its signature.
|
|
195
|
+
3. Runs your installer recipe with the signed copy as `@PAYLOAD@`.
|
|
196
|
+
4. Runs any `after_package` hook.
|
|
197
|
+
5. Signs the installer and checks that it is a valid installer of its format.
|
|
198
|
+
6. Checks every new signature: valid, timestamped, and from `publisher` when
|
|
199
|
+
configured.
|
|
200
|
+
7. Records the final checksum and the signature in `build.json`.
|
|
201
|
+
|
|
202
|
+
Your original input stays unchanged. Remove any SignTool `after_package` hook
|
|
203
|
+
when adopting this. MSIX targets are not signed automatically: their manifest
|
|
204
|
+
must name the certificate's exact subject, so keep signing them in an
|
|
205
|
+
`after_package` hook.
|
|
206
|
+
|
|
207
|
+
`sign-windows FILE...` signs the listed files in place and checks them the
|
|
208
|
+
same way. It needs the `windows.signing` section and all three account
|
|
209
|
+
variables, and fails rather than leaving a file unsigned.
|
|
210
|
+
|
|
211
|
+
## Sign on your own computer
|
|
212
|
+
|
|
213
|
+
On x64 Windows with the [Azure CLI](https://learn.microsoft.com/cli/azure/)
|
|
214
|
+
and the .NET 8 or newer runtime:
|
|
215
|
+
|
|
216
|
+
```powershell
|
|
217
|
+
az login
|
|
218
|
+
$env:AZURE_SIGNING_ENDPOINT = "https://weu.codesigning.azure.net/"
|
|
219
|
+
$env:AZURE_SIGNING_ACCOUNT = "example"
|
|
220
|
+
$env:AZURE_SIGNING_PROFILE = "example"
|
|
221
|
+
native-packages doctor --target windows-amd64
|
|
222
|
+
native-packages sign-windows .\hello.exe
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Your account needs the Certificate Profile Signer role on the signing account.
|
|
226
|
+
`native-packages doctor` checks the variables, the tools and the Azure CLI
|
|
227
|
+
sign-in without signing anything. `build --dry-run` shows whether Windows
|
|
228
|
+
signing is on under `windows_signing`.
|
|
229
|
+
|
|
230
|
+
## Tools and network access
|
|
231
|
+
|
|
232
|
+
Signing uses Microsoft's SignTool and the Artifact Signing client library
|
|
233
|
+
(dlib), the versions `azure/artifact-signing-action` 2.0.0 installs:
|
|
234
|
+
`Microsoft.Windows.SDK.BuildTools` 10.0.26100.4188 and
|
|
235
|
+
`Microsoft.ArtifactSigning.Client` 1.0.128. native-packages downloads them
|
|
236
|
+
from nuget.org on first use, checks each against a pinned SHA-256 on every
|
|
237
|
+
use, and keeps them under `%LOCALAPPDATA%\native-packages\windows-signing`.
|
|
238
|
+
To use local copies instead, for example without network access, set
|
|
239
|
+
`NATIVE_PACKAGES_SIGNTOOL` to an x64 `signtool.exe` and
|
|
240
|
+
`NATIVE_PACKAGES_ARTIFACT_SIGNING_DLIB` to the client's x64
|
|
241
|
+
`Azure.CodeSigning.Dlib.dll`.
|
|
242
|
+
|
|
243
|
+
The client library authenticates only through the Azure CLI: native-packages
|
|
244
|
+
excludes every other credential type, so an environment's client secret or a
|
|
245
|
+
developer's cached account can never sign instead. Signing reaches your
|
|
246
|
+
account's endpoint and Microsoft's timestamp service,
|
|
247
|
+
`http://timestamp.acs.microsoft.com`.
|
|
248
|
+
|
|
249
|
+
## Check the download
|
|
250
|
+
|
|
251
|
+
On Windows, check a downloaded installer:
|
|
252
|
+
|
|
253
|
+
```powershell
|
|
254
|
+
Get-AuthenticodeSignature .\hello-v1.2.3-windows-amd64.msi | Format-List Status, SignerCertificate, TimeStamperCertificate
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
`Status` should be `Valid`, with your organization in the signer certificate
|
|
258
|
+
and a timestamp. Artifact Signing certificates are valid for only a few days;
|
|
259
|
+
the timestamp keeps the signature valid after the certificate expires.
|
data/docs/_reference/commands.md
CHANGED
|
@@ -149,6 +149,20 @@ sign and notarize the copy. `--output` is required, must be new, and must be
|
|
|
149
149
|
outside the input. This command needs no project configuration. See
|
|
150
150
|
[Apple signing and notarization](../_guides/apple-notarization.md).
|
|
151
151
|
|
|
152
|
+
## sign-windows
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
native-packages sign-windows target/x86_64-pc-windows-msvc/release/hello.exe dist/hello-setup.exe
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Sign files in place with Azure Artifact Signing, with SHA-256 and an RFC 3161
|
|
159
|
+
timestamp, then check every signature. It needs the configuration's
|
|
160
|
+
`windows.signing` section, `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`,
|
|
161
|
+
`AZURE_SIGNING_PROFILE`, and an Azure CLI sign-in, and runs on x64 Windows.
|
|
162
|
+
Use it for files built outside native-packages; MSI and Inno targets sign
|
|
163
|
+
their installers during `build`. See
|
|
164
|
+
[Windows code signing](../_guides/windows-signing.md).
|
|
165
|
+
|
|
152
166
|
## Release checksums and signatures
|
|
153
167
|
|
|
154
168
|
```sh
|
|
@@ -187,13 +201,27 @@ Validate a stable tag and, when `version_file` is configured, compare it with
|
|
|
187
201
|
the application's Cargo manifest version. Set `version_section` for workspace
|
|
188
202
|
manifests.
|
|
189
203
|
|
|
204
|
+
## omarchy-recipe
|
|
205
|
+
|
|
206
|
+
```sh
|
|
207
|
+
native-packages omarchy-recipe ../omarchy-pkgs --release v1.2.3 [--package hello-bin]
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Write `pkgbuilds/NAME-bin/` in an omacom/omarchy-pkgs checkout from the
|
|
211
|
+
`arch/NAME-bin/` templates, rendered for that published release with
|
|
212
|
+
`pkgrel=1` and the hashes from `release.checksums`. Source URLs are rewritten
|
|
213
|
+
to follow `pkgver`, and `.omarchy/package.json` declares an `upstream.watch` on
|
|
214
|
+
the GitHub releases, so Omarchy's bot can update the package. The command downloads only the checksum manifest.
|
|
215
|
+
`--package` is required when several `-bin` templates exist. It refuses an
|
|
216
|
+
existing recipe directory. See [Omarchy packages](../_guides/omarchy.md).
|
|
217
|
+
|
|
190
218
|
## Select an installed tool version
|
|
191
219
|
|
|
192
220
|
If several gem versions are installed, RubyGems lets you select the one required
|
|
193
221
|
by the configuration:
|
|
194
222
|
|
|
195
223
|
```sh
|
|
196
|
-
native-packages _0.
|
|
224
|
+
native-packages _0.11.0_ build --version 1.2.3
|
|
197
225
|
```
|
|
198
226
|
|
|
199
227
|
Bundler also works if you prefer to manage the gem in a Gemfile.
|