Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 102 additions & 8 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,21 +1,33 @@
name: Release
# Fires when a version tag is pushed (e.g. `v0.4.0`). Cross-compiles static
# binaries (CGO_ENABLED=0; the SQLite driver is pure Go), writes SHA-256
# checksums, and publishes them as a GitHub Release with generated notes.
# binaries (CGO_ENABLED=0; the SQLite driver is pure Go) and writes a CycloneDX
# SBOM and SHA-256 checksums in one job; a second job, which runs no build or
# test code, attests build provenance and the SBOM for every archive (keyless,
# through Sigstore with its OIDC token) and publishes them as a GitHub Release
# with generated notes.
# The tag is the single source of the version: it is stamped into the binary
# with -ldflags, so `codeshot --version` can never disagree with the release.
# Verify a download: `gh attestation verify <archive> --repo inth3shadows/codeshot
# --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml
# --source-ref refs/tags/<tag>`.
on:
push:
tags:
- "v*"

permissions:
contents: write # create the GitHub Release + upload assets; nothing more
permissions: {}

jobs:
release:
name: Build + publish GitHub Release
# Runs the tests, the build and the SBOM tool, so it gets no signing
# permission: code here can't mint the OIDC token the attestations are
# signed with. It hands the release files to the publish job.
build:
name: Test, build + SBOM
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
version: ${{ steps.build.outputs.version }}
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
with:
Expand All @@ -29,8 +41,19 @@ jobs:
run: sudo apt-get update && sudo apt-get install -y graphviz && go test ./...

- name: Cross-compile
id: build
run: |
version="${GITHUB_REF_NAME#v}"
# A release tag is v<semver> (no leading zeros, optional pre-release):
# anything else would name the archives one way and give the SBOM a
# pseudo-version.
num='(0|[1-9][0-9]*)'
pre='(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)'
if ! [[ "$version" =~ ^$num\.$num\.$num(-$pre(\.$pre)*)?$ ]]; then
echo "::error::tag ${GITHUB_REF_NAME} is not v<major>.<minor>.<patch>[-<pre>]"
exit 1
fi
echo "version=${version}" >> "$GITHUB_OUTPUT"
mkdir -p dist
for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
os="${target%/*}"; arch="${target#*/}"
Expand All @@ -47,9 +70,80 @@ jobs:
tar -C dist -czf "dist/$name.tar.gz" "$name"
fi
done
(cd dist && sha256sum *.tar.gz *.zip > checksums.txt)
# One SBOM for the module (all six builds share its dependencies),
# pinned through the Go checksum database. The tag checkout gives it
# the version.
# -std lists the Go standard library compiled into every binary.
go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.12.0 \
mod -licenses -std -json -output "dist/codeshot_${version}.cdx.json"
(cd dist && sha256sum *.tar.gz *.zip *.cdx.json > checksums.txt)

- name: Hand the release files to the publish job
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release-files
path: |
dist/*.tar.gz
dist/*.zip
dist/*.cdx.json
dist/checksums.txt
if-no-files-found: error
retention-days: 7 # long enough to re-run publish on its own

# Signs and publishes; runs no build, test or third-party build code.
publish:
name: Attest + publish GitHub Release
needs: build
runs-on: ubuntu-latest
permissions:
contents: write # create the GitHub Release + upload assets
id-token: write # the OIDC token Sigstore signs the attestations with
attestations: write # store the provenance and SBOM attestations
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: release-files
path: dist
# The build job could add or swap files; only the expected release files,
# listed in checksums.txt and nothing else, get attested and published.
- name: Check the release files are exactly the expected ones
env:
VERSION: ${{ needs.build.outputs.version }}
run: |
cd dist
expected=$(
for t in linux_amd64 linux_arm64 darwin_amd64 darwin_arm64; do echo "codeshot_${VERSION}_${t}.tar.gz"; done
for t in windows_amd64 windows_arm64; do echo "codeshot_${VERSION}_${t}.zip"; done
echo "codeshot_${VERSION}.cdx.json"
)
expected=$(echo "$expected" | LC_ALL=C sort)
listed=$(awk '{ sub(/^\*/, "", $2); print $2 }' checksums.txt | LC_ALL=C sort)
present=$(ls -1A | grep -vx 'checksums.txt' | LC_ALL=C sort)
if [ "$listed" != "$expected" ] || [ "$present" != "$expected" ]; then
echo "::error::the release files are not exactly the expected seven"
diff <(echo "$expected") <(echo "$listed") || true
diff <(echo "$expected") <(echo "$present") || true
exit 1
fi
sha256sum -c checksums.txt

# Provenance for every archive and the SBOM, in one attestation over the
# checksums file; then the SBOM, attested for the archives it describes.
# actions/attest directly: attest-build-provenance and attest-sbom are
# wrappers around it, and attest-sbom is deprecated.
- name: Attest build provenance
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-checksums: dist/checksums.txt
- name: Attest the SBOM
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
with:
subject-path: |
dist/*.tar.gz
dist/*.zip
sbom-path: dist/codeshot_${{ needs.build.outputs.version }}.cdx.json

- name: Publish GitHub Release
env:
GH_TOKEN: ${{ github.token }}
run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/checksums.txt --generate-notes --title "${GITHUB_REF_NAME}"
run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/*.cdx.json dist/checksums.txt --repo "${GITHUB_REPOSITORY}" --generate-notes --title "${GITHUB_REF_NAME}"
20 changes: 19 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,30 @@ Generated diagrams are easy; trusted ones aren't. Tools like madge, pyan and go-

## Install

Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases) (checksums in `checksums.txt`), or build from source with Go 1.26+:
Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases), or build from source with Go 1.26+:

```bash
go install github.com/inth3shadows/codeshot/cmd/codeshot@latest
```

From v0.5.0 on, every release archive comes with a signed record of the workflow run that built it ([build provenance](https://slsa.dev/provenance/), keyless through Sigstore) and a [CycloneDX](https://cyclonedx.org/) SBOM, `codeshot_<version>.cdx.json`, attested for the same archives. To check a download with the [GitHub CLI](https://cli.github.com/):

```bash
sha256sum -c checksums.txt --ignore-missing # download intact (Linux; macOS: shasum -a 256 -c ...)
gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
--signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0
gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
--signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0 \
--predicate-type https://cyclonedx.org/bom # the SBOM attestation
```

The checksum line only shows the download is intact: `checksums.txt` comes from
the same release and isn't signed itself. The attestation is the proof of
origin. `--signer-workflow` and `--source-ref` require it to come from
`release.yml` running for that tag, not from any other workflow in the repo;
they trust whatever `release.yml` was at the tagged commit, so they are as
strong as the protection on `v*` tags.

Codeshot is a single static binary; it needs no Node of its own. `codeshot --version` prints the release version for release binaries and `go install ...@vX.Y.Z`, and `dev` for any other build.

**Requirements:**
Expand Down
2 changes: 1 addition & 1 deletion TECHNICAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe
codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md
```

CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git <FORK_SHA from ci.yml> && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node <cg>/dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release.
CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git <FORK_SHA from ci.yml> && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node <cg>/dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml` in two jobs. `build` (`contents: read` only) refuses a tag that isn't `v<semver>` (no leading zeros; an optional pre-release), runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module including the Go standard library (`cyclonedx-gomod` v1.12.0 `mod -licenses -std` through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, and uploads them as a one-day artifact. `publish` (`contents`, `id-token` and `attestations: write`) runs no build, test or third-party build code: it downloads the files, checks them against `checksums.txt`, refuses unless `checksums.txt` lists, and the artifact holds, exactly the seven expected files for the version (six archives and the SBOM), attests build provenance for them and the SBOM for the six archives (`actions/attest` v4.2.2 both times, SHA-pinned; `attest-build-provenance` and the deprecated `attest-sbom` are wrappers around it), and publishes the GitHub Release. Splitting the jobs keeps the OIDC token away from the tests and the SBOM tool's dependencies, which could otherwise mint it and attest any file as built here; a compromised build job can still change the bytes of the seven files it hands over, which no signing step can tell apart from a real build. The artifact is kept seven days, so `publish` can be re-run on its own. The attestations are keyless: Sigstore signs them with that token, and the workflow grants nothing at the top level. `gh attestation verify <archive> --repo inth3shadows/codeshot --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/<tag>` checks a download; it trusts whatever `release.yml` was at the tagged commit, so it is as strong as the protection on `v*` tags. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.

There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself.

Expand Down
Loading