How to zip → tar.gz in developer workflows
- Step 1Use it for quick PR/artifact triage — When a pull request or release ships a
.zip, drop it in, convert, andtar -tzf name.tar.gzto read the manifest. No clone, no shell, no temp dir — just confirm the contents look right before merging or deploying. - Step 2Check the schema before scripting — Call
GET /api/v1/tools/zip-to-tar-gzto retrieve the contract. This tool's schema has no options, so your automation payload is just the file — there are no parameters to set, validate, or version against. - Step 3Pair the local runner (paid tiers) — Install @jadapps/runner; it binds
http://127.0.0.1:9789on loopback. The web client auto-routes paid-tier jobs to it. For your own scripts,POST /v1/tools/zip-to-tar-gzwith the file payload — the runner converts on your machine and writes the output to a local path. - Step 4Build an artifact-normalisation step — In a pipeline that receives mixed
.zip/.7zartifacts, route them through the runner to emit uniform.tar.gzfor the next stage. Because there are no options, the step is a single call per file. - Step 5Decide CLI vs tool for reproducibility — If the build must be byte-reproducible, do NOT use this tool — it stamps
Date.now()as the mtime. Usetar --sort=name --mtime=... --owner=0 --group=0 --numeric-ownerinstead. Use the tool for non-deterministic, convenience conversions. - Step 6Attest the output — After conversion, generate a SHA-256 with the checksum generator and record it against the specific artifact. Don't re-derive the hash by re-converting — the mtime changes each run, so the digest won't match.
Automation surface
The real, code-backed ways to drive ZIP → TAR.GZ without clicking.
| Mechanism | Endpoint / call | Availability | Notes |
|---|---|---|---|
| Web client | drop + Process button | All tiers | No options panel; single file in, .tar.gz out |
| Schema discovery | GET /api/v1/tools/zip-to-tar-gz | API key | Returns empty option schema — no parameters |
| Local runner | POST http://127.0.0.1:9789/v1/tools/zip-to-tar-gz | Paid tiers | Loopback only; file never uploaded; writes to local path |
| Legacy runner port | http://127.0.0.1:49217 | Paid tiers (fallback) | Older v0.1.x runners during rollout |
Determinism checklist
What changes run-to-run, and the implication for CI.
| Aspect | Behaviour | CI implication |
|---|---|---|
| TAR mtime | Set to Date.now() each run | Output bytes differ → not cacheable / not reproducible |
| Entry mode | Always 0644 | Executable artifacts need post-extract chmod |
| GZIP level | Fixed at 6 | Consistent ratio, but no tuning |
| Entry order | Follows ZIP iteration order | Stable for a given input ZIP |
| Empty dirs | Dropped | Manifests differ from CLI tar czf output |
Cookbook
Developer-shaped recipes: triage, local automation, and the reproducibility boundary.
Triage a PR's release artifact without cloning
A PR attaches build.zip. Convert and list to sanity-check the contents before approving.
Drop build.zip → build.tar.gz $ tar -tzf build.tar.gz dist/index.js dist/index.js.map package.json # looks right — no node_modules accidentally bundled
Discover the (empty) schema before scripting
Confirm there are no options to pass — the payload is just the file.
$ curl -H 'Authorization: Bearer $KEY' \
https://jadapps…/api/v1/tools/zip-to-tar-gz
{
"slug": "zip-to-tar-gz",
"options": [] // no parameters for this tool
}Local runner call in a script (no upload)
Drive the conversion from a shell via the loopback runner on a paid tier; the artifact stays on disk.
# runner bound at 127.0.0.1:9789
curl -s -X POST \
http://127.0.0.1:9789/v1/tools/zip-to-tar-gz \
-F file=@build.zip
# → { outputPath: "…/build.tar.gz", sizeBytes: … }
# file never left the machineNormalise mixed artifacts to TAR.GZ
A stage receives .zip and .7z; emit uniform tarballs for the next step.
for f in incoming/*; do
curl -s -X POST \
http://127.0.0.1:9789/v1/tools/zip-to-tar-gz \
-F file=@"$f"
done
# all become *.tar.gz (7z read via WASM in the runner)Why NOT to use it for reproducible builds
Two conversions of the same ZIP produce different hashes. Use the CLI when bytes must be stable.
convert build.zip twice → two different sha256
(TAR mtime = Date.now() each run)
Reproducible alternative (CLI):
unzip -q build.zip -d /tmp/x
tar --sort=name --mtime='1970-01-01' \
--owner=0 --group=0 --numeric-owner \
-czf build.tar.gz -C /tmp/x . # stable hashEdge cases and what actually happens
Same ZIP, different output hash
Not deterministicThe TAR mtime is set to the current time on each conversion, so byte output and any checksum change between runs. Don't gate a CI cache on the converted hash, and don't re-derive an attestation by re-converting. For stable output, use the CLI with pinned --mtime/owner flags.
Expecting an options payload
Empty schemaGET /api/v1/tools/zip-to-tar-gz returns no options — this converter is parameterless. The OptionsPanel renders nothing in the UI and the runner ignores any options you send. If you need a compression level or path-strip, those live on other tools, not here.
Encrypted ZIP in an automated pipeline
RejectedAn encrypted archive fails with Archive contains encrypted entries… Provide a password to extract. There's no password parameter to pass via the runner, so the job errors. Branch on this message and route encrypted inputs to a password-capable tool first.
Runner not installed / not running
Falls backIf the @jadapps/runner isn't reachable on 127.0.0.1:9789 (or the legacy 49217), paid-tier jobs fall back to in-browser processing. For a headless script that relies on the runner, check GET /v1/health first and fail fast if it's down.
Executable bits lost on a CI binary
Not preservedOutput entries are mode 0644, so any executable produced upstream loses its +x bit through the conversion. Add a chmod +x after extraction in the consuming job, or skip the conversion and tar on the CLI where permissions survive.
Over-cap file in automation
Blocked (limit)Size is checked before processing — 50 MB free, 500 MB Pro, 2 GB top tiers. An over-cap artifact errors with the tier message. In CI, ensure the running account's tier matches the largest artifact you convert, or pre-split.
Manifest differs from tar czf output
ExpectedThe converter drops empty directories and bare directory entries, so tar -tzf on its output won't list ./ or empty folders the way a CLI tar czf . does. If a downstream check compares manifests exactly, account for this difference.
7z/RAR input in the runner
SupportedThe runner uses the same engines as the browser, so 7z/RAR/XZ/BZ2/ISO inputs convert via the WASM reader. Handy for normalising release assets that arrive in non-ZIP formats without installing unpackers on the build box.
Huge in-browser job blocks the tab
May fail (memory)When falling back to in-browser processing (no runner), a large or highly-expanding archive can exhaust the tab. The runner path on a server-class machine, or the CLI, is more robust for big inputs.
Comparing two artifacts
Use archive-diffTo compare what changed between two builds, don't diff converted tarball hashes (they drift on mtime). Use the archive diff tool, which compares entries and contents between two archives directly.
Frequently asked questions
Is there a real API for this tool?
Yes. GET /api/v1/tools/zip-to-tar-gz (with an API key) returns the tool's schema, and on paid tiers the local @jadapps/runner exposes POST http://127.0.0.1:9789/v1/tools/zip-to-tar-gz to run conversions locally. The schema is empty — the tool takes no options, only the file.
Does the runner upload my files?
No. The runner binds to loopback (127.0.0.1) and processes on your machine, writing the output to a local path. It exists precisely so paid-tier automation can run without uploading artifacts. The web client auto-routes to it when it's available.
Why isn't the output reproducible?
Each conversion stamps the current time as the TAR mtime, so two runs of the same ZIP produce different bytes and different hashes. There are no flags to pin the time. For reproducible builds use the CLI: tar --sort=name --mtime=... --owner=0 --group=0 --numeric-owner.
What options can I pass in automation?
None. This converter is parameterless — the schema returned by the API is an empty option set, the UI shows no options panel, and the runner ignores any options you send. The only input that matters is the file.
How do I handle encrypted ZIPs in a pipeline?
You can't convert them here — there's no password parameter, so the job fails with an encrypted-entries error. Detect it (e.g. with the encrypted archive detector), decrypt or extract with a password-capable tool such as the multi-format extractor, then convert the cleartext result.
Can I convert 7z or RAR release assets programmatically?
Yes. The runner uses the same WASM reader as the browser, so 7z, RAR, BZ2, XZ and ISO inputs convert to TAR.GZ without installing unpackers on the build box. For explicit target-format control, the archive format converter accepts a targetFormat of zip, tar.gz or gz.
What happens if the runner isn't running?
Paid-tier jobs fall back to in-browser processing. For headless scripts that depend on the runner, probe GET http://127.0.0.1:9789/v1/health first (a legacy fallback on 49217 exists for older runners) and fail fast if neither responds.
How do I attest the converted artifact?
Run it through the checksum generator (SHA-256) and record the digest against that exact file. Because re-converting changes the mtime and thus the hash, treat the produced tarball as canonical — never re-derive the checksum by re-running the conversion.
Can I use it during code review to inspect a ZIP artifact?
Yes — that's a sweet spot. Drop the PR's .zip, convert, and tar -tzf name.tar.gz to read the manifest without cloning or shelling out. It's a fast way to catch accidentally-bundled node_modules or secrets before approving.
Does it preserve permissions for CI binaries?
No — all entries come out mode 0644. Re-apply executable bits after extraction in the consuming job (chmod +x), or use the CLI unzip | tar czf where the source permissions carry through, when the binary must stay executable.
How do I diff two build artifacts reliably?
Don't compare converted-tarball hashes — they drift because of the mtime. Use the archive diff tool to compare the entries and contents of two archives directly, which is immune to metadata churn.
What's the largest artifact I can convert in CI?
Tier-bound: 50 MB free, 500 MB Pro, 2 GB Pro-media/Developer, with entry caps of 500 / 50,000 / 500,000 respectively. In-browser fallback is in-memory and can struggle with hugely-expanding archives; the runner on a server-class machine, or the CLI, is better for large inputs.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.