SameByte traces OCI artifact identity through GitHub Actions workflows. Changes should preserve the distinction between proven identity, unknown identity, coverage boundaries, and analysis errors. Start with the README for supported commands, adapters, findings, and limitations.
Use the issue forms. For an analyzer bug, include the SameByte version, a minimal workflow, any annotations, the command, and expected versus actual results. Remove credentials and private infrastructure details. A reduced example is usually more useful than a complete production workflow.
Discuss substantial changes to supported CI systems, dependency choices, or analysis semantics in an issue before implementing them. Small fixes and clarifications can go directly to a pull request.
Report vulnerabilities through the security policy, not a public bug report. Participation follows the code of conduct.
Use Node.js 22 or later and npm. CI tests Node.js 22 and 24 on Linux.
git clone https://github.com/0then0/samebyte.git
cd samebyte
npm ci --ignore-scripts
npm test
node dist/cli.js tests/fixtures/correct.ymlUse the committed npm lockfile. Do not replace it with another package manager's lockfile or update unrelated dependencies. Propose new dependencies with an explanation of why the existing tools are insufficient.
Keep changes focused. Add a regression test for a meaningful behavior change;
documentation-only changes do not require artificial tests. Tests use
node:test, assertions, and CLI subprocesses. Single-file workflow fixtures live
in tests/fixtures; caller and callee fixtures for reusable workflows live in
tests/fixtures/reusable/.github/workflows, because callees are located from a
repository root. Avoid registry access, container
execution, or running upstream workflow scripts in tests.
npm run typecheck
npm run lint
npm test
npm pack --dry-runnpm test builds the CLI and test bundles before running tests and fails when the
committed action bundle action/index.mjs is stale. After changing anything under
src/, or updating yaml, @actions/expressions or esbuild, run
npm run build:action and commit the regenerated bundle; Dependabot cannot do
this, so dependency pull requests need that extra commit. npm pack --dry-run checks the installable package and also builds the CLI. To format
changes, run npm run format, then inspect the diff for unrelated edits.
.editorconfig uses UTF-8, LF, and two-space indentation. Biome defines the
TypeScript and JSON formatting rules. Git preserves the original bytes of
checksum-pinned files under docs/evidence/*/upstream/; do not reformat them.
Saved reports in docs/evidence/reports/ are generated with
docs/evidence/replay.mjs; regenerate them after a change that alters report output. See the
workflow examples for reproduction commands. Never
execute those upstream actions or scripts as part of regeneration.
For analyzer changes, preserve these invariants:
- Unresolved or independently produced symbolic digests are not proven unequal.
- Source tests do not prove that an OCI artifact was tested.
- Conditions, execution order, ignored failures, and platform selection matter.
- An unsupported action or script is a coverage boundary, not a guessed operation.
- Each reusable workflow call has its own scope; a callee check gates a caller deployment only when it cannot be skipped or ignored.
- Trusted annotations do not establish that a step has no additional behavior.
- Exit codes remain
0for no high-confidence findings,1for such findings, and2for analysis errors.
src/parser.ts: discovery, YAML locations, structural checks, dependency ordering.src/expressions.ts: GitHub expression AST, symbolic values, env propagation, OCI identities.src/reusable.ts: repository root, local reusable workflow path checks and bounded loading.src/adapters.tsandsrc/shell.ts: action interfaces, a restricted shell tokenizer, and shell resolution.src/analyzer.tsandsrc/model.ts: transfer of values and artifact/operation graph.src/rules.ts: identity relationships, check ordering, and findings.src/output.ts,src/run.tsandsrc/cli.ts: text, JSON, SARIF, graph, report files, and process exit codes.src/action.tsandaction/index.mjs: the GitHub Action entrypoint and its committed bundle.
Dependabot checks npm dependencies and GitHub Actions on the first day of each month. New versions must be at least seven days old. Minor and patch updates are grouped per ecosystem; major updates use separate PRs, and at most one version-update PR per ecosystem is open at a time. Security updates are not delayed by this schedule. Updates require review and passing CI.
Create a branch in your fork and open a pull request against main. Explain the
problem, resulting behavior, and commands used to verify it. Link a related issue
when one exists. Include documentation updates for changed public behavior.
Use English Conventional Commit messages with feat, fix, refactor, chore,
docs, or test, for example fix: retain coverage for annotated shell steps.
CI must pass on both supported Node.js versions before merge. Do not commit
build output, local credentials, or release archives. The one exception is
action/index.mjs: GitHub runs the action from the tagged commit, so its bundle
is committed and verified against the sources.
Maintainers publish GitHub Releases from stable vX.Y.Z tags. The tag must match
package.json. Only the release job has repository write permissions; ordinary
CI has read-only access.
- Update
package.jsonandpackage-lock.json, for example withnpm version patch --no-git-tag-version --ignore-scripts. - Set the matching version in
src/cli.tsand the version assertion intests/cli.test.ts, then runnpm run build:action. Update the README anddocs/github-action.mdversion examples and changelog; retain historical versions in the evidence reports. - Run the verification commands above. Check
node dist/cli.js --versionand ensure the package contains only the intended files. - Commit the release preparation. Create an annotated tag on that commit, for
example
git tag -a vX.Y.Z -m "SameByte vX.Y.Z", replacingX.Y.Zwith the actual version. - Push the commit and tag together with
git push --atomic origin main refs/tags/vX.Y.Z. - Wait for CI and the release workflow. Check that the published release includes
samebyte-X.Y.Z.tgzandSHA256SUMS, then verify the downloaded checksum and CLI version.
Do not move published tags or replace existing release assets to fix a release. Prepare a new patch release instead. SameByte distributes packages through GitHub Releases; this workflow does not publish to the npm registry.
Contributions are distributed under the project's Apache-2.0 license.