native-packages 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/CONTRIBUTING.md +1 -1
  3. data/README.md +5 -2
  4. data/docs/_guides/building-packages.md +5 -0
  5. data/docs/_guides/distribution-recipes.md +3 -1
  6. data/docs/_guides/getting-started.md +2 -2
  7. data/docs/_guides/github-actions.md +6 -4
  8. data/docs/_guides/hosted-repositories.md +170 -0
  9. data/docs/_guides/multi-platform.md +1 -1
  10. data/docs/_guides/native-recipes.md +6 -2
  11. data/docs/_guides/omarchy.md +131 -0
  12. data/docs/_guides/prereleases.md +1 -1
  13. data/docs/_guides/publishing.md +19 -0
  14. data/docs/_guides/release-signing.md +4 -4
  15. data/docs/_guides/windows-signing.md +259 -0
  16. data/docs/_reference/commands.md +32 -3
  17. data/docs/_reference/configuration.md +33 -3
  18. data/docs/_reference/platforms.md +126 -8
  19. data/docs/_reference/troubleshooting.md +22 -2
  20. data/docs/index.md +1 -1
  21. data/docs/releasing.md +2 -2
  22. data/examples/native-packages-all-formats.yaml +1 -1
  23. data/examples/native-packages-linux-distribution.yaml +76 -0
  24. data/examples/native-packages.yaml +1 -1
  25. data/lib/native_packages/appimage.rb +4 -66
  26. data/lib/native_packages/apt_repository.rb +190 -0
  27. data/lib/native_packages/build.rb +59 -6
  28. data/lib/native_packages/cli.rb +19 -2
  29. data/lib/native_packages/configuration.rb +29 -2
  30. data/lib/native_packages/dnf_repository.rb +131 -0
  31. data/lib/native_packages/flatpak.rb +171 -0
  32. data/lib/native_packages/flatpak_repository.rb +63 -0
  33. data/lib/native_packages/hosted_repository.rb +73 -0
  34. data/lib/native_packages/inspection.rb +3 -2
  35. data/lib/native_packages/macos_signing.rb +20 -2
  36. data/lib/native_packages/omarchy.rb +140 -0
  37. data/lib/native_packages/openpgp.rb +114 -0
  38. data/lib/native_packages/snap.rb +166 -0
  39. data/lib/native_packages/staging.rb +74 -0
  40. data/lib/native_packages/support.rb +1 -1
  41. data/lib/native_packages/windows_signing.rb +284 -0
  42. metadata +15 -1
@@ -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.12.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.
@@ -97,8 +97,9 @@ native-packages publish --from dist/linux --to github --target linux-amd64
97
97
  ```
98
98
 
99
99
  `--from` selects the build directory; `--to` lists destinations separated by
100
- commas. `github` uploads release assets. Other names select entries or groups
101
- in `repositories`.
100
+ commas. `github` uploads release assets, `snapcraft` uploads snaps to the
101
+ Snap Store, and `apt`, `dnf` and `flatpak` write the signed repositories configured under
102
+ `apt`, `dnf` and `flatpak.repository`. Other names select entries or groups in `repositories`.
102
103
 
103
104
  The build must be complete and its recorded files unmodified. Repeated
104
105
  `--target` options require exactly those targets, with all their formats.
@@ -149,6 +150,20 @@ sign and notarize the copy. `--output` is required, must be new, and must be
149
150
  outside the input. This command needs no project configuration. See
150
151
  [Apple signing and notarization](../_guides/apple-notarization.md).
151
152
 
153
+ ## sign-windows
154
+
155
+ ```sh
156
+ native-packages sign-windows target/x86_64-pc-windows-msvc/release/hello.exe dist/hello-setup.exe
157
+ ```
158
+
159
+ Sign files in place with Azure Artifact Signing, with SHA-256 and an RFC 3161
160
+ timestamp, then check every signature. It needs the configuration's
161
+ `windows.signing` section, `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT`,
162
+ `AZURE_SIGNING_PROFILE`, and an Azure CLI sign-in, and runs on x64 Windows.
163
+ Use it for files built outside native-packages; MSI and Inno targets sign
164
+ their installers during `build`. See
165
+ [Windows code signing](../_guides/windows-signing.md).
166
+
152
167
  ## Release checksums and signatures
153
168
 
154
169
  ```sh
@@ -187,13 +202,27 @@ Validate a stable tag and, when `version_file` is configured, compare it with
187
202
  the application's Cargo manifest version. Set `version_section` for workspace
188
203
  manifests.
189
204
 
205
+ ## omarchy-recipe
206
+
207
+ ```sh
208
+ native-packages omarchy-recipe ../omarchy-pkgs --release v1.2.3 [--package hello-bin]
209
+ ```
210
+
211
+ Write `pkgbuilds/NAME-bin/` in an omacom/omarchy-pkgs checkout from the
212
+ `arch/NAME-bin/` templates, rendered for that published release with
213
+ `pkgrel=1` and the hashes from `release.checksums`. Source URLs are rewritten
214
+ to follow `pkgver`, and `.omarchy/package.json` declares an `upstream.watch` on
215
+ the GitHub releases, so Omarchy's bot can update the package. The command downloads only the checksum manifest.
216
+ `--package` is required when several `-bin` templates exist. It refuses an
217
+ existing recipe directory. See [Omarchy packages](../_guides/omarchy.md).
218
+
190
219
  ## Select an installed tool version
191
220
 
192
221
  If several gem versions are installed, RubyGems lets you select the one required
193
222
  by the configuration:
194
223
 
195
224
  ```sh
196
- native-packages _0.10.0_ build --version 1.2.3
225
+ native-packages _0.12.0_ build --version 1.2.3
197
226
  ```
198
227
 
199
228
  Bundler also works if you prefer to manage the gem in a Gemfile.
@@ -28,7 +28,7 @@ expressions. Use the replacement values listed below.
28
28
  | Field | Purpose |
29
29
  | --- | --- |
30
30
  | `schema` | Required. Set to `1`. |
31
- | `tool.version` | Required. Exact native-packages version, such as `'0.10.0'`. |
31
+ | `tool.version` | Required. Exact native-packages version, such as `'0.12.0'`. |
32
32
  | `tool.nfpm` | Required. Set to `'2.47.0'`, including in native-only configurations. |
33
33
  | `nfpm` | Shared package metadata and installed-file mappings, or a relative YAML filename. Requires `name`. |
34
34
  | `targets` | Required. Named build targets; use `{}` for recipe-only projects. |
@@ -40,6 +40,11 @@ expressions. Use the replacement values listed below.
40
40
  | `revisions` | Package revision numbers by app version and recipe path. |
41
41
  | `version_file` | Cargo manifest checked by `check-version`. |
42
42
  | `version_section` | Cargo section to check; defaults to `package`. |
43
+ | `windows` | Optional. `windows.signing` turns on [Windows code signing](#windows-signing). |
44
+ | `flatpak` | Required by `flatpak` targets: the app ID, runtime, command and permissions. See [Flatpak](platforms.md#flatpak). |
45
+ | `snap` | Required by `snap` targets: the base, confinement and apps, and the Snap Store channels. See [Snap](platforms.md#snap). |
46
+ | `apt` | Optional signed APT repository for `publish --to apt`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
47
+ | `dnf` | Optional signed DNF repository for `publish --to dnf`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
43
48
 
44
49
  Quote tool versions so they remain strings. A version mismatch reports the
45
50
  command needed to install and select the configured gem.
@@ -98,8 +103,8 @@ letters, digits, and hyphens, starting with a letter or digit.
98
103
  | `native` | Required for DMG, MSI and Inno. Contains `command` and `output`. |
99
104
  | `appimage` | Optional for AppImage targets: `update_information`, embedded with a `.zsync` file beside the AppImage. See [AppImage](platforms.md#update-information). |
100
105
 
101
- Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `srpm`,
102
- `msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
106
+ Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `flatpak`,
107
+ `snap`, `srpm`, `msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
103
108
 
104
109
  Windows targets select only `[msix]`, `[msi]` or `[inno]`; macOS targets select `[dmg]`.
105
110
  DMG, MSI and Inno each require a separate binary target. SRPM requires a separate
@@ -154,6 +159,31 @@ For DMGs, automatic Apple input signing finishes before the native command.
154
159
  DMG signing and notarization run after `after_package`, before the final hash.
155
160
  See [Apple signing and notarization](../_guides/apple-notarization.md).
156
161
 
162
+ ## Windows signing
163
+
164
+ ```yaml
165
+ windows:
166
+ signing:
167
+ provider: azure-artifact-signing
168
+ description: Hello
169
+ description_url: https://example.org/hello
170
+ publisher: Example Ltd
171
+ ```
172
+
173
+ | Field | Purpose |
174
+ | --- | --- |
175
+ | `provider` | Required. `azure-artifact-signing`. |
176
+ | `description` | Program name shown in Windows' permission prompts. Defaults to the package name. |
177
+ | `description_url` | An `https://` URL in the signature. Defaults to `nfpm.homepage`. |
178
+ | `publisher` | Optional. The organization every signature must name, checked after signing. |
179
+
180
+ The account comes from the environment, never the file:
181
+ `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT` and `AZURE_SIGNING_PROFILE`.
182
+ With none set, builds are unsigned; an incomplete set fails. With all three,
183
+ MSI and Inno builds sign the input's unsigned code before the native command,
184
+ and the installer after `after_package`, before the final hash. See
185
+ [Windows code signing](../_guides/windows-signing.md).
186
+
157
187
  ## Replacement values
158
188
 
159
189
  Strings can contain `@KEY@` values. Unknown or unavailable values cause an error.
@@ -14,17 +14,19 @@ libraries.
14
14
 
15
15
  | Format | Target | What you supply | Packaging tools |
16
16
  | --- | --- | --- | --- |
17
- | `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries. |
18
- | `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries. |
17
+ | `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries; `gpg` for a hosted APT repository. |
18
+ | `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries; `createrepo_c` and `gpg` for a hosted DNF repository. |
19
19
  | `archlinux` | Linux | Arch-compatible files and explicit dependencies. | nFPM, `readelf` for binaries. |
20
20
  | `apk` | Linux | Suitable Alpine files, usually musl or static binaries, and dependencies. | nFPM, `readelf` for binaries. |
21
21
  | `ipk` | Linux | Files for the device/distribution baseline, dependencies, and an `abi` label. | nFPM, `readelf` for binaries. |
22
22
  | `appimage` | Linux | The same files as the DEB/RPM, including one desktop entry and its icon. | `mksquashfs` (squashfs-tools), `curl`, `readelf`; `zsyncmake` (zsync) with update information. |
23
+ | `flatpak` | Linux | The same files as the DEB/RPM, under `/usr`, and a top-level `flatpak` section. | `flatpak`, `readelf`; `ostree` and `gpg` to publish a repository. |
24
+ | `snap` | Linux | The same files as the DEB/RPM and a top-level `snap` section. | `mksquashfs` (squashfs-tools), `readelf`; `snapcraft` to upload to the Snap Store. |
23
25
  | `srpm` | Linux source target | RPM spec and source files. | nFPM; native RPM tooling for rebuild tests. |
24
26
  | `msix` | Windows | Windows binaries, identity, application assets, and capabilities. | nFPM; Windows tools for signing and installation tests. |
25
27
  | `dmg` | macOS | Complete app and a DMG script. | macOS, `lipo`, and your script's tools, such as `hdiutil`. |
26
- | `msi` | Windows | Complete app and a Windows Installer recipe/wrapper, such as a WiX project. | Windows and your installed MSI toolset, such as WiX. |
27
- | `inno` | Windows | Complete app and an Inno Setup recipe/wrapper. | Windows and your installed Inno compiler. |
28
+ | `msi` | Windows | Complete app and a Windows Installer recipe/wrapper, such as a WiX project. | Windows and your installed MSI toolset, such as WiX; optional Azure Artifact Signing. |
29
+ | `inno` | Windows | Complete app and an Inno Setup recipe/wrapper. | Windows and your installed Inno compiler; optional Azure Artifact Signing. |
28
30
 
29
31
  The supported nFPM version is **2.47.0**. It writes package files from your
30
32
  prepared contents. Native DMG, MSI and Inno targets call your scripts instead.
@@ -123,6 +125,120 @@ pattern. An `after_package` hook must leave the AppImage as it is, or the
123
125
  Running an AppImage needs FUSE on the user's system, or
124
126
  `./App.AppImage --appimage-extract-and-run`.
125
127
 
128
+ ## Flatpak
129
+
130
+ Add `flatpak` to a Linux binary target's `formats` (`amd64` or `arm64`) and
131
+ describe the app once, at the top level:
132
+
133
+ ```yaml
134
+ flatpak:
135
+ id: org.example.Hello
136
+ runtime: org.freedesktop.Platform
137
+ runtime_version: '24.08'
138
+ sdk: org.freedesktop.Sdk
139
+ command: hello
140
+ metainfo: packaging/org.example.Hello.metainfo.xml
141
+ runtime_repo: https://dl.flathub.org/repo/flathub.flatpakrepo
142
+ finish_args:
143
+ - --socket=wayland
144
+ - --socket=fallback-x11
145
+ - --share=ipc
146
+ - --share=network
147
+ ```
148
+
149
+ | Field | Purpose |
150
+ | --- | --- |
151
+ | `id` | Required. The reverse-DNS application ID. |
152
+ | `runtime`, `runtime_version` | Required. The runtime the app runs on, such as `org.freedesktop.Platform` `24.08`. |
153
+ | `sdk` | Optional. Recorded for `flatpak run --devel`; nothing is built with it. |
154
+ | `command` | Required. A program in `/usr/bin` (which becomes `/app/bin`), or an absolute `/app` path. |
155
+ | `finish_args` | The app's sandbox permissions, as `flatpak build-finish` options. |
156
+ | `metainfo` | Optional AppStream file, installed as `ID.metainfo.xml`. It must declare `<id>ID</id>`. |
157
+ | `branch` | Defaults to `stable`. |
158
+ | `runtime_repo` | Optional `.flatpakrepo` URL from which `flatpak install` fetches a missing runtime. |
159
+ | `repository` | Optional [self-hosted Flatpak repository](../_guides/hosted-repositories.md#flatpak) for `publish --to flatpak`. |
160
+
161
+ The bundle holds the same `contents` as the other formats, with `/usr`
162
+ becoming `/app`; a file installed anywhere else fails the build. A contents
163
+ entry with `packager: flatpak` is included only in the Flatpak. Flatpak
164
+ exports only files named after the app ID, so the package's one desktop entry
165
+ becomes `ID.desktop`, its `Icon` becomes the ID, and the icon files it names
166
+ are renamed to match.
167
+
168
+ The output is `NAME-VERSION-ARCH.flatpak` (`x86_64` or `aarch64`), a
169
+ single-file bundle users install with `flatpak install --user FILE`. The app
170
+ is already built, so native-packages writes the metadata and runs
171
+ `flatpak build-finish`, `build-export` and `build-bundle` on the staged
172
+ files. No flatpak-builder, SDK or network is needed, and nothing is compiled
173
+ in the sandbox. Runtimes installed on the build host are hidden from
174
+ `build-finish`, so they cannot add permissions. The same inputs and
175
+ `SOURCE_DATE_EPOCH` give the same OSTree commit, which `build.json` records;
176
+ the bundle file around it also records when it was written, so its hash
177
+ changes between builds.
178
+
179
+ **Libraries come from the runtime.** The binary must run against the
180
+ runtime's libraries, or the package must install the others under `/usr/lib`.
181
+ Test the app in the sandbox with the permissions you declared.
182
+
183
+ native-packages does not write Flathub manifests or submit apps to Flathub,
184
+ because Flathub does not accept AI-assisted manifests or submissions. Write
185
+ and submit a Flathub manifest yourself if you want to publish there.
186
+
187
+ ## Snap
188
+
189
+ Add `snap` to a Linux binary target's `formats` and describe the snap once,
190
+ at the top level. The fields follow `snap.yaml`:
191
+
192
+ ```yaml
193
+ snap:
194
+ base: core24
195
+ confinement: strict
196
+ grade: stable
197
+ icon: /usr/share/icons/hicolor/scalable/apps/hello.svg
198
+ apps:
199
+ hello:
200
+ command: usr/bin/hello
201
+ desktop: usr/share/applications/hello.desktop
202
+ plugs: [wayland, x11, opengl, network, audio-playback]
203
+ store:
204
+ channels: [stable]
205
+ ```
206
+
207
+ | Field | Purpose |
208
+ | --- | --- |
209
+ | `name` | Defaults to `nfpm.name`. 2 to 40 lowercase letters, digits and hyphens. |
210
+ | `base` | Required, such as `core24`. |
211
+ | `confinement` | `strict` (default), `classic` or `devmode`. |
212
+ | `grade` | `stable` (default) or `devel`. |
213
+ | `summary`, `description`, `license`, `title` | Default to the first line of `nfpm.description`, the description and `nfpm.license`. The summary has at most 78 characters. |
214
+ | `apps` | Required. Each app's `command` is a path inside the snap, such as `usr/bin/hello`, and may also set `plugs`, `slots`, `environment`, `daemon` and the other `snap.yaml` app fields. |
215
+ | `apps.APP.desktop` | Optional desktop entry the package installs. It is copied to `meta/gui/APP.desktop`, launching the app. |
216
+ | `icon` | Optional `.png` or `.svg` the package installs; it becomes `meta/gui/icon` and the desktop entries' `Icon`. |
217
+ | `plugs`, `slots`, `layout`, `environment` | Optional top-level `snap.yaml` sections, passed through. |
218
+ | `store.channels` | Channels for `publish --to snapcraft`, such as `stable` or `latest/edge`. |
219
+
220
+ The package's `contents` become the snap's root (`/usr/bin/hello` is
221
+ `$SNAP/usr/bin/hello`), beside a generated `meta/snap.yaml`. A contents entry
222
+ with `packager: snap` is included only in the snap. The output is
223
+ `NAME_VERSION_ARCH.snap` with Snap's architecture names (`amd64`, `arm64`,
224
+ `armhf`, `ppc64el`, `s390x`, `riscv64`). It is an xz SquashFS image owned by
225
+ root, packed with mksquashfs as `snap pack` packs a prime directory. No
226
+ snapcraft, LXD or network is involved, and the same inputs and
227
+ `SOURCE_DATE_EPOCH` give the same bytes.
228
+
229
+ **Libraries come from the base snap or the package.** A strictly confined
230
+ snap does not see the host's libraries, and no snapcraft extension (such as
231
+ `gnome` or `kde-neon`) is applied, so a dynamically linked desktop app needs
232
+ its libraries among the contents and an `environment` that points at them.
233
+ Static binaries need nothing more. Install the snap with
234
+ `snap install --dangerous FILE` and test it under its confinement before
235
+ uploading.
236
+
237
+ `publish --to snapcraft` uploads each snap in the build with
238
+ `snapcraft upload --release=CHANNELS`. The Snap Store login comes from
239
+ `SNAPCRAFT_STORE_CREDENTIALS` (from `snapcraft export-login`), never the
240
+ configuration, and the snap's name must already be registered.
241
+
126
242
  ## MSIX
127
243
 
128
244
  MSIX targets use `platform: windows`, `formats: [msix]`, and PE binaries with
@@ -149,7 +265,8 @@ target with a local directory input. macOS inspection supports `amd64`,
149
265
 
150
266
  Follow [macOS and Windows installers](../_guides/native-recipes.md) for setup.
151
267
  DMG targets can automatically [sign and notarize](../_guides/apple-notarization.md)
152
- when complete Apple credentials are available.
268
+ when complete Apple credentials are available. MSI and Inno targets can sign
269
+ their code and installer with [Azure Artifact Signing](../_guides/windows-signing.md).
153
270
 
154
271
  ## Distribution recipes
155
272
 
@@ -162,9 +279,10 @@ An Arch package file and an AUR recipe are separate outputs: the former can
162
279
  be installed directly; the latter tells Arch tooling how to obtain and package
163
280
  your app.
164
281
 
165
- There is no Flatpak or Snap build/publication adapter, no NSIS adapter, and no
166
- hosted APT/DNF index service. Keep those workflows in your app's release
167
- process if you need them.
282
+ native-packages can also write signed APT, DNF and Flatpak repositories from
283
+ your DEB, RPM and Flatpak packages, served as static files; see
284
+ [Hosted package repositories](../_guides/hosted-repositories.md). There is no
285
+ NSIS adapter. Keep that workflow in your app's release process if you need it.
168
286
 
169
287
  ## What validation establishes
170
288
 
@@ -23,8 +23,8 @@ working on with `doctor --target ID` and `build --target ID --dry-run`.
23
23
  Install and select the version named in the error:
24
24
 
25
25
  ```sh
26
- gem install native-packages --version 0.10.0
27
- native-packages _0.10.0_ doctor
26
+ gem install native-packages --version 0.12.0
27
+ native-packages _0.12.0_ doctor
28
28
  ```
29
29
 
30
30
  `tool.version` is an exact match. In CI, use the matching released reusable
@@ -165,6 +165,26 @@ A native script must package `@PAYLOAD@` and preserve its signatures. A failure
165
165
  from Apple's service prevents a completed signed build. Use the submission
166
166
  information in the error to investigate Apple's result before retrying.
167
167
 
168
+ ## Windows signing fails or is skipped
169
+
170
+ Signing needs the configuration's `windows.signing` section and all three of
171
+ `AZURE_SIGNING_ENDPOINT`, `AZURE_SIGNING_ACCOUNT` and `AZURE_SIGNING_PROFILE`.
172
+ None means an unsigned build; an incomplete set fails. `native-packages doctor`
173
+ checks them and the Azure CLI sign-in.
174
+
175
+ - `AADSTS700213: No matching federated identity record found` from
176
+ `azure/login`: the federated credential's subject differs from the token's.
177
+ Repositories that present GitHub's immutable subject need
178
+ `repo:OWNER@OWNER_ID/REPOSITORY@REPOSITORY_ID:environment:NAME`; see
179
+ [Windows code signing](../_guides/windows-signing.md#2-trust-your-github-workflow-with-the-right-subject).
180
+ - `403 Forbidden` from SignTool: the endpoint's region differs from the
181
+ account's, the account or profile name is wrong, or the identity lacks the
182
+ Artifact Signing Certificate Profile Signer role.
183
+ - A publisher mismatch: the certificate profile is not the one
184
+ `windows.signing.publisher` names.
185
+ - A pinned SHA-256 mismatch: nuget.org served a different SignTool or client
186
+ package. The download is deleted; do not override the hash.
187
+
168
188
  ## Get help
169
189
 
170
190
  If the error persists, [open an issue](https://github.com/crmne/native-packages/issues)
data/docs/index.md CHANGED
@@ -25,7 +25,7 @@ features:
25
25
  details: Describe your app's files, package metadata, and build targets in a single YAML file.
26
26
  - icon: 🐧
27
27
  title: Linux packages
28
- details: Create DEB, RPM, AppImage, Arch, Alpine, and IPK packages from your compatible Linux builds.
28
+ details: Create DEB, RPM, AppImage, Flatpak, Snap, Arch, Alpine, and IPK packages from your compatible Linux builds.
29
29
  - icon: 🖥️
30
30
  title: Native installers
31
31
  details: Connect your macOS DMG script and your Windows MSI or Inno Setup script, or package Windows apps as MSIX.
data/docs/releasing.md CHANGED
@@ -23,7 +23,7 @@ Update the gemspec, `NativePackages::VERSION`, example/version references and ch
23
23
  Create a GitHub release for that commit:
24
24
 
25
25
  ```sh
26
- gh release create v0.10.0 --target main --title 'native-packages 0.10.0' --notes-file release-notes.md
26
+ gh release create v0.12.0 --target main --title 'native-packages 0.12.0' --notes-file release-notes.md
27
27
  ```
28
28
 
29
29
  Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.
@@ -36,7 +36,7 @@ If the workflow itself needs a correction, fix it on `main` and dispatch the
36
36
  corrected release workflow against the existing published tag:
37
37
 
38
38
  ```sh
39
- gh workflow run release.yml --ref main -f tag=v0.10.0
39
+ gh workflow run release.yml --ref main -f tag=v0.12.0
40
40
  ```
41
41
 
42
42
  Validation resolves the original tag to an exact commit, requires it to be on
@@ -1,7 +1,7 @@
1
1
  # Supply the listed build outputs before running this example.
2
2
  schema: 1
3
3
  tool:
4
- version: '0.10.0'
4
+ version: '0.12.0'
5
5
  nfpm: '2.47.0'
6
6
  nfpm:
7
7
  name: example-app