CI & Releases
| Getting Started | Using the App | Technical Reference | Project |
|---|---|---|---|
| Home | Usage Guide | Architecture | Repository |
| Installation | Conversion Methods | XDVDFS Technical Docs | Building from Source |
| XISO Explorer | Troubleshooting & FAQ | CI & Releases |
This page describes how XISO Studio is built, tested, documented, and released. Everything runs in GitHub Actions; no local machine is required to cut a release.
- Repository: https://github.com/purelogiccode/XISOStudio
- Actions: https://github.com/purelogiccode/XISOStudio/actions
- Releases: https://github.com/purelogiccode/XISOStudio/releases
- Wiki: https://github.com/purelogiccode/XISOStudio/wiki
- Documentation site: https://purelogiccode.github.io/XISOStudio/
Workflows
| Workflow | File | Trigger | Purpose |
|---|---|---|---|
| CI | .github/workflows/ci.yml |
Push / pull request to master, manual |
Restore, build in Release, test on Windows/Linux/macOS, collect coverage, run InspectCode (gating), validate documentation, and publish six RID artifacts |
| Release | .github/workflows/release.yml |
Push of a release_MAJOR.MINOR.PATCH tag, manual dispatch |
Re-run the three-platform tests, verify the tag matches the project version, build and validate the six bundles, and create or update the GitHub release |
| Update Wiki | .github/workflows/wiki.yml |
Push to docs/**, manual |
Copy docs/*.md into the GitHub wiki, rewrite .md links, verify the published page, and verify the Pages build for the same commit |
| Deploy Pages | .github/workflows/pages.yml |
Push to docs/**, manual |
Build the Jekyll site with GitHub Pages and deploy it through the Pages environment |
CI stages
- Build & test matrix -
windows-latest,ubuntu-latest, andmacos-latestrestore and build the solution in Release, then run the full xUnit suite. The Linux leg also collectsXPlat Code Coverageand uploads it as thecoverageartifact. - InspectCode - installs the pinned JetBrains command-line tools, runs
jb inspectcode --swea, uploads the SARIF report, and fails when the report contains any finding. The solution is expected to stay at zero. - Documentation - verifies that every documentation page is reachable from the side menus and
that internal
.mdlinks resolve, then builds the Jekyll site to catch Liquid or layout errors. - Publish - cross-publishes all six runtime identifiers (
win-x64,win-arm64,linux-x64,linux-arm64,osx-x64,osx-arm64) as framework-dependent single-file artifacts.
Release stages
- Test - runs the suite on Windows, Linux, and macOS against the tagged commit.
- Version guard - the tag must match
<Version>,<AssemblyVersion>, and<FileVersion>inXISOStudio/XISOStudio.csproj. A mismatch fails the release before anything is published. - Build bundles - publishes each RID with
--self-contained false -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true, stages the required files, restores Unix execute bits, and writesrelease_<version>_<rid>.zip. - Validate bundles - checks the six expected archive names, the complete file list in each
archive, and the execute bit on
XISOStudioand the bundled 7-Zip helper. - Publish - writes the release notes from the matching section of
Release Notes, creates or updates the GitHub release, and uploads all bundles
plus
SHA256SUMS.txt.
Release Bundles
Every release publishes six archives. The name is part of the update contract:
release_MAJOR.MINOR.PATCH_<rid>.zip
release_3.2.2_win-x64.zip
release_3.2.2_win-arm64.zip
release_3.2.2_linux-x64.zip
release_3.2.2_linux-arm64.zip
release_3.2.2_osx-x64.zip
release_3.2.2_osx-arm64.zip
The application does not download a specific asset; UpdateChecker reads the latest release tag,
extracts the numeric version, and offers the release page. Keeping the MAJOR.MINOR.PATCH part of the
tag intact is therefore what makes the in-app update check work.
Bundle contents
Each archive contains these files at its root (no wrapping folder):
| File | Notes |
|---|---|
XISOStudio.exe / XISOStudio |
Framework-dependent single-file executable; the .NET 11 runtime is not embedded |
7za.exe + 7za_arm64.exe |
Windows bundles only; 7-Zip CLI fallback for x64 and ARM64 |
7zz_linux_x64 / 7zz_linux_arm64 |
Matching Linux bundle only |
7zz_osx |
Both macOS bundles (universal binary) |
7-Zip-License.txt |
License for the bundled 7-Zip binaries |
ReadMe.md |
Project overview, badges, and installation instructions |
WhatsNew.md |
Highlights of the current release |
LICENSE.txt |
GNU GPL v3.0 |
Linux and macOS executables keep the Unix execute bit inside the ZIP (0755, stored in the ZIP
external attributes as 0x81ED << 16), so extracting without unzip permission loss leaves the app
runnable. chmod +x XISOStudio 7zz_* remains a safe fallback.
Local bundle archive
Finished bundles are also kept in the repository working tree under XISOStudio/bin/Release/. That
folder is an append-only archive: existing release_*.zip files are never deleted, moved, or
overwritten. New bundles are built in a temporary staging folder and only the final ZIP is copied in.
This is why the folder contains historical releases next to the current one.
Documentation Publishing
docs/ is the single source for two destinations, and both show the same side menu:
- GitHub wiki -
docs/_Sidebar.mdis the menu. The Update Wiki workflow clones the wiki repository, copiesdocs/*.md, renamesindex.mdtoHome.md, rewrites.mdlinks, pushes, and checks the publishedHome.mdfor the current version. - GitHub Pages -
docs/_layouts/default.htmlrenders the menu for every page, anddocs/_config.ymlholds the title, description, and theme. The Deploy Pages workflow builds the site with GitHub Pages and deploys it through thegithub-pagesenvironment.
Every documentation page also starts with the same four-column navigation table, so the docs stay navigable when read directly in the repository. When adding or renaming a page, update:
docs/_Sidebar.md(wiki menu)docs/_layouts/default.html(Pages menu)- The page’s top navigation table
docs/index.md(documentation map)
The wiki sync requires a repository secret named WIKI_TOKEN - a personal access token with repo
scope, because the default GITHUB_TOKEN cannot push to the wiki repository. When the secret is
absent, the sync step is skipped with a notice.
Cutting a Release
- Update
WhatsNew.md,ReadMe.md,docs/Release-Notes.md,docs/index.md, andXISOStudio/XISOStudio.csprojto the new version. -
Run the full suite locally:
dotnet build CSharp_XISOStudio.sln -c Release dotnet test CSharp_XISOStudio.sln -c Release --no-build - Commit the release preparation and push
master. -
Tag and push:
git tag release_3.2.2 git push origin master git push origin release_3.2.2 - The tag triggers the Release workflow, which tests, validates, builds the six bundles, and publishes the GitHub release. The docs push triggers the wiki sync and the Pages deployment.
- Optionally build the bundles locally into the append-only archive
(
XISOStudio/bin/Release/) using the samedotnet publishsettings as the workflow.
Verifying a release
- Actions: all jobs green, including the InspectCode, documentation, and bundle validation steps.
- Release assets: six
release_<version>_<rid>.zipfiles plusSHA256SUMS.txt. - Update check: launching the previous version should offer the new release page.
- Wiki:
Home.mdshows the new version. - Pages: https://purelogiccode.github.io/XISOStudio/ shows the new version on the home page.
Troubleshooting the Pipeline
| Symptom | Cause | Fix |
|---|---|---|
| Release fails with “Tag release_X does not match the project version” | The csproj version and the tag disagree | Update all three version fields in XISOStudio.csproj, commit, and re-tag |
| Wiki step logs “WIKI_TOKEN is not set” | Missing repository secret | Add a PAT with repo scope as WIKI_TOKEN |
| Pages deployment is skipped or fails | Pages source is not configured | Set Settings → Pages → Build and deployment → Source to GitHub Actions |
| Bundle validation fails on the execute bit | The archive was created on Windows without mode attributes | Build on Linux/macOS or set the ZIP external attributes (0x81ED << 16) before uploading |
| InspectCode fails | A new finding was introduced | Fix the finding and re-run jb inspectcode CSharp_XISOStudio.sln |
See Repository for the repository layout and Building from Source for local build and publish commands.