CI and releases
The goal is to build on every OS your developers use, run each platform's outputs on a machine of that platform, and release packages from a tag without a stored secret. The workflow below follows the AsmSdk repository's own CI and release workflows.
A complete GitHub Actions workflow
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
build:
strategy:
fail-fast: false
matrix:
include:
- { os: windows-2025, rid: win-x64 }
- { os: windows-11-arm, rid: win-arm64 }
- { os: ubuntu-24.04, rid: linux-x64 }
- { os: ubuntu-24.04-arm, rid: linux-arm64 }
- { os: macos-15, rid: osx-arm64 }
runs-on: ${{ matrix.os }}
env:
DOTNET_NOLOGO: "1"
NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
global-json-file: global.json # only if global.json pins "sdk"; else dotnet-version: 10.0.x
- uses: actions/cache@v4
with:
path: .nuget/packages # holds the SDK and the toolchain package
key: nuget-${{ runner.os }}-${{ hashFiles('global.json', '**/*.asmproj', '**/*.csproj', '**/Directory.*.props') }}
- run: dotnet build App.slnx -c Release -warnaserror
- run: dotnet test App.slnx -c Release --no-build # each runner calls its own platform's build
- name: Run this platform's program
shell: bash
run: ./HelloApp/bin/Release/libc/${{ matrix.rid }}/hello-app${{ runner.os == 'Windows' && '.exe' || '' }}
- run: dotnet pack App.slnx -c Release -o artifacts/packages --no-build
if: matrix.rid == 'linux-x64'
- uses: actions/upload-artifact@v4
if: matrix.rid == 'linux-x64'
with:
name: packages
path: artifacts/packages/*.nupkg
What each part is for
The matrix: one runner per platform that has one. Every runner builds all the RIDs, since any build machine does, and the bundled toolchain differs per host. Each runner then runs its own platform's outputs:
osx-x64runs onmacos-15too, under Rosetta 2, andwin-x64onwindows-11-arm, under Windows' x64 emulation;linux-musl-x64runs onubuntu-24.04in an Alpine container (docker run … alpine).
GitHub's ARM64 runners (
ubuntu-24.04-arm,windows-11-arm) are free for public repositories.NUGET_PACKAGESplus the cache: keeps the SDK and the toolchain (tens of MB) from being downloaded on every run. The key includes the project files because they decide which packages restore.-warnaserror: makes MSBuild warnings fail the build. NASM's own warnings count only if the projects set<AsmFlags>-Xvc</AsmFlags>, which turns them into MSBuild warnings, orTreatWarningsAsErrors=true, which makes NASM itself fail. Set both inDirectory.Build.propsfor asm projects.--no-buildonpack: packs exactly what was built and tested. One runner packs: every runner built the same seven RIDs.Running the outputs: a Linux freestanding executable runs on any Linux runner of its CPU. A
libcone needs glibc 2.34+, whichubuntu-22.04and later have.Tests that P/Invoke the library: a test project's portable build carries every RID of the asm project, as an app does, so the same
dotnet teston each runner calls that runner's own build.Pre-release SDKs: while a project uses an SDK version that is not on nuget.org, commit the folder feed, or download it in a step before the build, and keep a
nuget.configmapping as in References and packages.
Versioning
One version for every package in a repository: set
<Version>inDirectory.Build.props.Version from the tag: override it at release time with
dotnet pack -p:Version=${GITHUB_REF_NAME#v}. A tagv1.2.0gives packages1.2.0.Pre-releases:
1.3.0-preview.1. NuGet sorts them before1.3.0, and consumers opt in by asking for a pre-release version.Semantic Versioning for asm libraries:
Change Version bump export removed, or a contract broken (arguments, return value, a struclayout ininclude/)major export added minor implementation only patch inspect_output.py --jsonlists the exports, so a CI step can diff them against the previous release.
Releasing to nuget.org with trusted publishing
Trusted publishing exchanges a short-lived GitHub OIDC token for a nuget.org API key valid for one hour, so no secret is stored. Setup:
- On nuget.org: Account → Trusted Publishing → Add. Fill in the owner (user or
organization), the repository owner, the repository, and the workflow file name
(
release.yml). Optionally restrict it to a GitHub environment. - Write the workflow:
# .github/workflows/release.yml
name: Release
on:
push:
tags: ['v*']
permissions:
contents: write # create the GitHub release
id-token: write # OIDC token for nuget.org
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: 10.0.x
- run: dotnet pack App.slnx -c Release -o artifacts/packages -p:Version=${GITHUB_REF_NAME#v}
- run: ./HelloApp/bin/Release/libc/linux-x64/hello-app # smoke-test before publishing
- name: NuGet login (OIDC)
id: login
uses: NuGet/login@v1
with:
user: ${{ vars.NUGET_USER }} # the nuget.org account or organization
- run: dotnet nuget push "artifacts/packages/*.nupkg" -s https://api.nuget.org/v3/index.json -k ${{ steps.login.outputs.NUGET_API_KEY }} --skip-duplicate
- run: gh release create "$GITHUB_REF_NAME" artifacts/packages/*.nupkg --generate-notes
env:
GH_TOKEN: ${{ github.token }}
--skip-duplicate: a re-run of a partly published release does not fail on the packages already pushed.- Before the first push: reserve the package id prefix on nuget.org, so nobody else can publish under your ids.
Reproducibility
- Deterministic outputs: AsmSdk links with
--build-id=sha1on Linux and-Breproon Windows (the id and the timestamp computed from the content). ld64.lld derives a Mach-O file's UUID from the content too. Archives are written withllvm-ar rcsD(zero timestamps and ids). The same inputs give byte-identical outputs. - On Linux, the checkout folder is one of those inputs. NASM records each source's
absolute path in an ELF object's symbol table, and in DWARF in Debug builds, and ld.lld
keeps it. A Release
.sobuilt fromC:/src/xdiffers from one built from/home/ci/x. Measured from two folders: thewin-x64DLL and theosx-x64dylib came out byte-identical, while the Linux.sofiles did not. For identical Linux outputs across machines, do one of these:- build from the same absolute path everywhere (a fixed CI workspace);
- strip the static symbol table in Release:
<LinkerArg Include="-s" />(Linux RIDs only) removes the paths and keeps the exported (dynamic) symbols.
- Checking it: build on two runners and compare SHA-256 hashes of the outputs. A difference means an input differs, such as a define, a toolchain version or a path.
- Pinned inputs:
global.jsonpins the SDK;- the SDK pins the toolchain, or
AsmToolchainVersiondoes; packages.lock.jsonwith--locked-modepins packages.
- The .NET SDK version matters little to the native output, but pin it with
global.json's"sdk"section anyway, for reproducible restores.
Other CI systems
Any system that can run dotnet works:
- Azure Pipelines:
UseDotNet@2, then the same commands. Cache$(NUGET_PACKAGES)withCache@2. - GitLab CI: the
mcr.microsoft.com/dotnet/sdk:10.0image, acache:entry for.nuget/packages, and the same commands. Its glibc also runslinux-x64libcoutputs. - Jenkins or TeamCity: the same commands on any agent. Each agent runs the outputs of its own platform.