buckit/docs/release-process.md

Buckit Release Process

Cutting a Release

Stable release

git tag RELEASE.2026-05-10T23-30-35Z
git push origin RELEASE.2026-05-10T23-30-35Z

Or generate the timestamp automatically:

TAG=RELEASE.$(date -u +%Y-%m-%dT%H-%M-%SZ)
git tag $TAG
git push origin $TAG

Release candidate

TAG=RELEASE.$(date -u +%Y-%m-%dT%H-%M-%SZ).rc1
git tag $TAG
git push origin $TAG

Tag format

The tag must follow RELEASE.YYYY-MM-DDTHH-MM-SSZ exactly. All components (year, month, day, hour, minute, second) are required. The build will fail if any part is missing.

Examples:

• RELEASE.2026-05-10T23-30-35Z — stable
• RELEASE.2026-05-10T23-30-35Z.rc1 — release candidate

What Happens Automatically

Once you push a tag, the Release workflow (.github/workflows/release.yml) triggers. Monitor it at:

https://github.com/buckit-io/buckit/actions/workflows/release.yml

Or via CLI:

gh run list --workflow=release.yml --repo buckit-io/buckit

The workflow runs these jobs in order:

1. build — Compiles binaries for linux/amd64, linux/arm64, windows/amd64, darwin/arm64. Signs each with minisign. Generates .deb, .rpm, .apk packages (Linux only).
2. docker — Builds and pushes multi-arch Docker images to ghcr.io and Docker Hub.
3. publish — Creates a GitHub Release with all artifacts attached.
4. update-gh-pages — Updates the self-update pointer on GitHub Pages (stable releases only).

All jobs should show ✅. If any job fails, click into it to see the error log.

Release candidates skip the :latest Docker tag and the gh-pages update.

Downloading Releases

Binaries

# Linux
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z

# macOS
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-darwin-arm64.RELEASE.2026-05-10T23-30-35Z

# Windows
curl -LO https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-windows-amd64.exe.RELEASE.2026-05-10T23-30-35Z

Docker

docker pull ghcr.io/buckit-io/buckit:latest
docker pull buckitio/buckit:latest

# Or a specific version:
docker pull ghcr.io/buckit-io/buckit:RELEASE.2026-05-10T23-30-35Z

Run with Docker

# Basic single-node server
docker run -p 9000:9000 -p 9001:9001 ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# With persistent storage
docker run -p 9000:9000 -p 9001:9001 -v ~/buckit-data:/data ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# With custom credentials
docker run -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=myadmin \
  -e MINIO_ROOT_PASSWORD=mysecretpassword \
  -v ~/buckit-data:/data \
  ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# Run in background
docker run -d --name buckit -p 9000:9000 -p 9001:9001 -v ~/buckit-data:/data ghcr.io/buckit-io/buckit:latest server /data --console-address :9001

# View logs
docker logs buckit

# Stop
docker stop buckit

Access the console at http://localhost:9001 and the S3 API at http://localhost:9000. Default credentials: buckitadmin / buckitadmin.

Linux Packages

DEB (Debian/Ubuntu):

wget https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit_20260510233035.0.0_amd64.deb
dpkg -i buckit_20260510233035.0.0_amd64.deb

RPM (RHEL/Fedora):

dnf install https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-20260510233035.0.0-1.x86_64.rpm

APK (Alpine):

wget https://github.com/buckit-io/buckit/releases/download/RELEASE.2026-05-10T23-30-35Z/buckit-20260510233035.0.0-r0.apk
apk add --allow-untrusted buckit-20260510233035.0.0-r0.apk

The packages install the binary to /usr/local/bin/buckit and include a systemd service unit at /lib/systemd/system/minio.service.

Verifying Signatures

Each binary has a .minisig signature file. To verify:

minisign -Vm buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z \
  -x buckit-linux-amd64.RELEASE.2026-05-10T23-30-35Z.minisig \
  -p buckit.pub

The public key (buckit.pub) is in the repository root.

Upgrading a Running Server

Using mc admin update

mc admin update <alias>

This automatically discovers the latest release and performs a rolling update across all nodes in the cluster.

How it works: the server fetches a small buckit.sha256sum pointer file from GitHub Pages to check if a newer version exists. One file per platform:

https://buckit-io.github.io/buckit/server/buckit/release/linux-amd64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/linux-arm64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/windows-amd64/buckit.sha256sum
https://buckit-io.github.io/buckit/server/buckit/release/darwin-arm64/buckit.sha256sum

Each file contains one line (<sha256> buckit.RELEASE.<timestamp>) which the server uses to determine the latest version and verify the downloaded binary. These files are updated automatically on each stable release (not RCs) via the gh-pages branch.

You can also point to a specific release or a private mirror:

mc admin update <alias> https://my-mirror.example.com/buckit/linux-amd64/buckit.sha256sum

Manual upgrade

Download the new binary, replace the old one, restart the service.

Secrets

These are configured in GitHub Actions (Settings → Secrets):

Secret	Purpose
MINISIGN_PRIVATE_KEY	Signs release binaries
MINISIGN_PASSWORD	Passphrase for the signing key
DOCKERHUB_USERNAME	Pushes images to Docker Hub
DOCKERHUB_TOKEN	Docker Hub access token

GITHUB_TOKEN is provided automatically by GitHub Actions.

Infrastructure

Service	Purpose	URL
GitHub Releases	Binary/package hosting	https://github.com/buckit-io/buckit/releases
GitHub Pages	Self-update pointer (buckit.sha256sum)	https://buckit-io.github.io/buckit/
ghcr.io	Docker images	ghcr.io/buckit-io/buckit
Docker Hub	Docker images (mirror)	docker.io/buckitio/buckit

Workflow File

The release workflow lives at .github/workflows/release.yml.