native-packages 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +1 -1
- data/README.md +5 -2
- data/docs/_guides/building-packages.md +5 -0
- data/docs/_guides/distribution-recipes.md +3 -1
- data/docs/_guides/getting-started.md +2 -2
- data/docs/_guides/github-actions.md +6 -4
- data/docs/_guides/hosted-repositories.md +170 -0
- data/docs/_guides/multi-platform.md +1 -1
- data/docs/_guides/native-recipes.md +6 -2
- data/docs/_guides/omarchy.md +131 -0
- data/docs/_guides/prereleases.md +1 -1
- data/docs/_guides/publishing.md +19 -0
- data/docs/_guides/release-signing.md +4 -4
- data/docs/_guides/windows-signing.md +259 -0
- data/docs/_reference/commands.md +32 -3
- data/docs/_reference/configuration.md +33 -3
- data/docs/_reference/platforms.md +126 -8
- data/docs/_reference/troubleshooting.md +22 -2
- data/docs/index.md +1 -1
- data/docs/releasing.md +2 -2
- data/examples/native-packages-all-formats.yaml +1 -1
- data/examples/native-packages-linux-distribution.yaml +76 -0
- data/examples/native-packages.yaml +1 -1
- data/lib/native_packages/appimage.rb +4 -66
- data/lib/native_packages/apt_repository.rb +190 -0
- data/lib/native_packages/build.rb +59 -6
- data/lib/native_packages/cli.rb +19 -2
- data/lib/native_packages/configuration.rb +29 -2
- data/lib/native_packages/dnf_repository.rb +131 -0
- data/lib/native_packages/flatpak.rb +171 -0
- data/lib/native_packages/flatpak_repository.rb +63 -0
- data/lib/native_packages/hosted_repository.rb +73 -0
- data/lib/native_packages/inspection.rb +3 -2
- data/lib/native_packages/macos_signing.rb +20 -2
- data/lib/native_packages/omarchy.rb +140 -0
- data/lib/native_packages/openpgp.rb +114 -0
- data/lib/native_packages/snap.rb +166 -0
- data/lib/native_packages/staging.rb +74 -0
- data/lib/native_packages/support.rb +1 -1
- data/lib/native_packages/windows_signing.rb +284 -0
- metadata +15 -1
|
@@ -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.
|
data/docs/_reference/commands.md
CHANGED
|
@@ -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
|
|
101
|
-
|
|
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.
|
|
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.
|
|
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`, `
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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.
|
|
27
|
-
native-packages _0.
|
|
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.
|
|
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.
|
|
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
|