native-packages 0.9.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d89f67e56b034b1cc13d55891e7a88d32e4a607c2c79d44df51c7115f65a7a8d
4
- data.tar.gz: b1d29fef3871480632f7557f3af5de763bbd7fa67e1ef04b792eb598e3352c49
3
+ metadata.gz: ac048cc41a4da6fce8d7fb71973cac33e9f8590eea8e78c0817d4a5edf09b78f
4
+ data.tar.gz: 04222cbfdc2f7fbf432506bf5d68d752a3bee15b158e95d42ec6ce70f869b039
5
5
  SHA512:
6
- metadata.gz: 1d2b77dd672a81d231398884f02b4077c123f7cc05d6dff7b6fbed62417f2a7854ad7557245dc1fc291f0cd78884f799f6c97b0c96de003bc1ceaba16539550e
7
- data.tar.gz: e77790947545f9086ec1ec16caf3c6226ae8bc398d860c40cced2939d1d4b65262c0d66067e9d545272ef14df3b92a7648111303e1cc8efc6a7e93439d4e8aa8
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.9.0.gem
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
@@ -49,6 +49,10 @@ path dependency. To test changes from a local theme checkout, use Bundler's
49
49
  temporary path configuration or a separate Gemfile, and keep that local setup
50
50
  out of the committed lockfile.
51
51
 
52
+ Social previews use the launch-film poster, configured under
53
+ `jekyll_vitepress.seo.image` in `docs/_config.yml`. Keep it a JPEG or PNG with
54
+ matching width, height, and alt text; the SVG logo is for the site itself.
55
+
52
56
  ### Writing a guide
53
57
 
54
58
  Put tutorials in `docs/_guides/` and reference pages in `docs/_reference/`.
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: 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.9.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.9.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.9.0
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.9.0` with that release's
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.9.0
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.9.0
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
 
@@ -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.9.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 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
@@ -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.9.0` for readability. For release workflows, replace it
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.9.0
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.9.0
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.
@@ -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.9.0_ build --version 1.2.3
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.