Z-Edit

Smart file editor launcher — opens files in the right editor based on MIME type or extension

View project on GitHub
↑ Up to Z-Tools Portfolio

zedit — CI/CD & Release Guide

Audience: This guide is written for contributors and maintainers who are new to GitHub Actions and the GitHub release workflow. No prior CI/CD experience is assumed.

Table of Contents

  1. What is CI/CD?
  2. Key concepts
  3. How zedit’s release pipeline works
  4. Step-by-step: publishing a new release
  5. What happens on GitHub automatically
  6. The release assets explained
  7. Monitoring a running workflow
  8. Troubleshooting
  9. Local build (without CI)

1. What is CI/CD?

CI stands for Continuous Integration — automatically building and testing code every time a change is pushed.

CD stands for Continuous Delivery (or Deployment) — automatically packaging and publishing software so users can install it without manual steps.

Together, CI/CD replaces the error-prone human process of:

developer builds on their laptop → manually zips files → uploads to a server

with a fully automated, reproducible process that runs on GitHub’s servers every time you push a tag.

2. Key concepts

Concept What it means
GitHub Actions GitHub’s built-in CI/CD platform. Free for public repositories.
Workflow A YAML file in .github/workflows/ that describes what to do and when to do it.
Job A unit of work inside a workflow. Each job runs on a fresh virtual machine.
Step A single command (or reusable action) inside a job.
Trigger The event that starts a workflow (e.g. pushing a tag).
Tag A named pointer to a specific Git commit, used to mark releases (e.g. v0.5.0).
GitHub Release A page on GitHub that lists a specific version, its changelog, and downloadable files.
Asset A file attached to a GitHub release (e.g. a .tar.gz archive).
Action A reusable, community-supplied workflow step (e.g. actions/checkout@v4).
Runner The virtual machine GitHub spins up to execute a job (ubuntu-latest = Ubuntu Linux).

3. How zedit’s release pipeline works

Workflow file location

.github/
└── workflows/
    └── release.yml    ← the entire CI/CD definition lives here

Trigger: push a version tag

The workflow starts only when a tag whose name starts with v is pushed to the repository:

on:
  push:
    tags:
      - 'v*'

Tags like v0.5.0, v1.0.0, v2.3.1-beta all match. Regular branch pushes (e.g. pushing to master) do not trigger this workflow.

Pipeline diagram

Developer pushes tag v0.5.0
        │
        ▼
GitHub detects the tag push
        │
        ▼
GitHub Actions starts a fresh Ubuntu VM
        │
        ├─ Step 1: Checkout source code
        │
        ├─ Step 2: Set up Python 3.11
        │
        ├─ Step 3: Install cmake + python3-magic
        │
        ├─ Step 4: Extract version number from tag ("v0.5.0" → "0.5.0")
        │
        ├─ Step 5: Configure build  (cmake -B build)
        │
        ├─ Step 6: Build install archive  → zedit-0.5.0-Linux.tar.gz
        │
        ├─ Step 7: Build source archive   → zedit-0.5.0-source.tar.gz
        │
        ├─ Step 8: Resolve asset filenames
        │
        └─ Step 9: Create GitHub Release
                   • Title: "zedit v0.5.0"
                   • Auto-generated changelog
                   • Attaches both .tar.gz files as downloadable assets

Permissions

The workflow is granted write access to repository contents so it can create the release:

permissions:
  contents: write

This is the minimum permission required; no other GitHub resources are touched.

4. Step-by-step: publishing a new release

Prerequisites

  • Git installed and configured on your machine.
  • You have push access to proteus-cpi/zedit.
  • The gh CLI is installed (optional — only needed if you want to create a release locally without pushing a tag).

Step 1 — Update the version number

Open CMakeLists.txt and bump the VERSION field:

project(zedit
    VERSION      0.6.0   # ← change this
    ...
)

Commit the change:

git add CMakeLists.txt
git commit -m "release: bump version to 0.6.0"

Step 2 — Push the commit

git push

Step 3 — Create and push the tag

The tag name must start with v followed by the version number:

git tag v0.6.0
git push origin v0.6.0

That single git push origin v0.6.0 command is the only manual action required to trigger the entire release pipeline.

Step 4 — Wait for the workflow to finish (~2 minutes)

Monitor progress at:

https://github.com/proteus-cpi/zedit/actions

When the workflow succeeds, the release is published automatically at:

https://github.com/proteus-cpi/zedit/releases/tag/v0.6.0

5. What happens on GitHub automatically

Once the tag is pushed GitHub Actions:

  1. Provisions a fresh Ubuntu virtual machine — nothing from previous runs can affect the build. This guarantees reproducibility.

  2. Checks out the exact commit the tag points to — users always get the code that matches the version number.

  3. Installs all build dependencies — cmake and python3-magic are installed fresh each time.

  4. Runs CMake to configure the project and generate a CPack configuration.

  5. Runs CPack (via the tarball CMake target) to create the install archive. CPack stages files into a temporary directory under /opt/zedit/... without touching the runner’s real filesystem.

  6. Runs git archive to produce a clean source tarball — this contains only the files tracked by Git (no build artefacts, no editor swap files).

  7. Creates the GitHub Release using the softprops/action-gh-release action, which:

    • Sets the release title to zedit vX.Y.Z
    • Auto-generates a changelog from commit messages since the previous tag
    • Uploads both .tar.gz files as release assets

6. The release assets explained

Each release ships two archives:

zedit-X.Y.Z-Linux.tar.gz — Install archive

This is the ready-to-use binary distribution. It contains the full directory tree that gets installed under /opt/zedit, pre-laid-out so you can extract it directly to /:

opt/
└── zedit/
    ├── bin/
    │   └── zedit          ← main executable
    ├── share/
    │   └── doc/zedit/     ← documentation
    └── etc/zedit/         ← default config

To install:

sudo tar -xzf zedit-0.5.0-Linux.tar.gz -C /

To uninstall:

sudo rm -rf /opt/zedit

zedit-X.Y.Z-source.tar.gz — Source archive

This is a clean snapshot of the source code at the tagged commit. It is equivalent to what you would get from git clone, minus the .git history. Use this if you want to inspect the code, build from source on a different platform, or audit the release.

To build from source:

tar -xzf zedit-0.5.0-source.tar.gz
cd zedit-0.5.0-source/
cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/zedit
cmake --build build --target tarball   # or: --target deb

7. Monitoring a running workflow

  1. Go to https://github.com/proteus-cpi/zedit/actions
  2. Click the workflow run that appeared after you pushed the tag.
  3. Click any step to expand its log output in real time.
  4. A green tick (✓) means the step passed; a red cross (✗) means it failed.

You will also receive a GitHub notification email when the workflow finishes (pass or fail), provided email notifications are enabled in your GitHub account settings.

8. Troubleshooting

Workflow did not start

  • Verify the tag name starts with v: git tag -l lists all local tags.
  • Verify the tag was actually pushed to GitHub: check the Tags tab on the repository page.
  • Check the Actions tab for any workflow run (even a failed one) triggered by the tag.

Build step failed

Click the failed step in the Actions UI to read the full log. Common causes:

Symptom Likely cause Fix
cmake: command not found apt-get step failed Check network connectivity of the runner
CPack: package not generated CMakeLists.txt syntax error Fix locally, commit, re-tag
Permission denied on release creation contents: write missing Ensure the permissions: block is in the workflow
Tag already exists You tried to re-push an existing tag Delete old tag: git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z

Re-running after a fix

If the workflow fails and you push a fix to the same tag, you need to delete and re-create the tag because a tag is an immutable pointer:

# Delete tag locally and on GitHub
git tag -d v0.6.0
git push origin :refs/tags/v0.6.0

# Re-tag after fixing the code
git add <changed files>
git commit -m "fix: ..."
git tag v0.6.0
git push && git push origin v0.6.0

9. Local build (without CI)

You can produce the same release assets on your own machine without pushing a tag. This is useful for testing packaging changes before publishing.

# Configure
cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/zedit

# Build install archive
cmake --build build --target tarball
# → build/zedit-X.Y.Z-Linux.tar.gz

# Build source archive
VERSION=$(grep -m1 'VERSION' CMakeLists.txt | awk '{print $2}')
git archive --format=tar.gz \
  --prefix="zedit-${VERSION}-source/" \
  -o "zedit-${VERSION}-source.tar.gz" \
  HEAD
# → zedit-X.Y.Z-source.tar.gz

# Optionally create a GitHub release manually (requires gh CLI)
gh release create vX.Y.Z \
  --title "zedit vX.Y.Z" \
  --notes "Release notes here" \
  build/zedit-X.Y.Z-Linux.tar.gz \
  zedit-X.Y.Z-source.tar.gz

Tip: Always prefer the automated CI path for official releases. Local builds may include uncommitted files or differ from the tagged source, breaking reproducibility.