From ab552323a6ac25323ce4612583bc69259c260c62 Mon Sep 17 00:00:00 2001 From: Ben Davis <45952064+bmdavis419@users.noreply.github.com> Date: Mon, 12 Oct 2026 23:16:43 -0700 Subject: [PATCH] CHORE: Add GitHub Actions CI and install/contributing docs --- .github/workflows/check.yml | 56 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++++ README.md | 45 +++++++++++++++++++++++++ 3 files changed, 168 insertions(+) create mode 100644 .github/workflows/check.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml new file mode 100644 index 0000000..531e5db --- /dev/null +++ b/.github/workflows/check.yml @@ -0,0 +1,56 @@ +name: check + +# GitHub Actions gate for contributors without Depot CI access. +# .depot/workflows/check.yml remains the release gate (full `make check` +# plus the site checks); this workflow covers the Go module only and +# needs no Docker daemon, secrets, or network beyond module downloads. +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +concurrency: + group: check-${{ github.ref }} + cancel-in-progress: true + +jobs: + go-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Go + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: go.mod + cache: true + + - name: gofmt check + run: | + unformatted="$(gofmt -l .)" + if [ -n "$unformatted" ]; then + echo "gofmt: unformatted files:" >&2 + echo "$unformatted" >&2 + echo "run 'make format' and commit the result" >&2 + exit 1 + fi + + - name: go vet + run: go vet ./... + + - name: go build + run: go build ./... + + # Docker integration tests self-skip unless TX9_TEST_DOCKER_IMAGE + # names an already-installed shell-capable image (see + # internal/docker), so this stays green and fast without a daemon. + # To run them locally: + # docker pull ubuntu:24.04 + # TX9_TEST_DOCKER_IMAGE=ubuntu:24.04 go test ./internal/docker/ + - name: go test + run: go test ./... diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4cf132c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing + +## Prerequisites + +- Go matching `go.mod` (currently Go 1.26) — verify with `go version` +- Bash, Make, Python 3 (with PyYAML), `jq`, `gzip`, `tar` +- ShellCheck v0.11.0 for `make check` +- Docker, only for running boxes or the opt-in Docker integration tests +- Node 22.18+ with npm, only for the `site/` Worker checks + +## Build + +```bash +make tx9 # build ./bin/tx9 (VERSION=0.12.0 make tx9 to stamp a version) +make dist # cross-compile release binaries + checksums.txt into dist/ +go run . # run without building; reports version "dev" +``` + +The CLI embeds its build context (`box.env`, `provision/`, `guest/`, `docker/`) at compile time, so rebuild after editing those files before testing `tx9 create`. + +## Test + +```bash +make check # full gate: syntax, ShellCheck, guest regressions, gofmt, go vet, go test ./... +make format # gofmt -w . +go test -buildvcs=false ./... # Go tests only +go test -buildvcs=false -race ./... # with the race detector +``` + +GitHub Actions (`.github/workflows/check.yml`) runs the gofmt check, `go vet ./...`, `go build ./...`, and `go test ./...` on pushes to `main` and every pull request. Depot CI (`.depot/workflows/check.yml`) additionally runs the full `make check` and the site checks, and remains the release gate. + +### Docker integration tests + +Go tests that need a real Docker daemon self-skip unless `TX9_TEST_DOCKER_IMAGE` names an already-installed image with `/bin/sh`, `cat`, `ls`, and `sleep`. They create only disposable containers and never mount host data: + +```bash +docker pull ubuntu:24.04 +TX9_TEST_DOCKER_IMAGE=ubuntu:24.04 go test -buildvcs=false ./internal/docker/ +``` + +Running boxes end to end (`tx9 create`, `tx9 enter`, `tx9 doctor`) also needs a running Docker daemon and is not part of CI. + +### Site checks + +```bash +cd site +npm ci --ignore-scripts +npm run check && npm run format:check && npm run lint && npm test +``` + +## Makefile targets + +| Target | What it does | +| -------------- | --------------------------------------------------------------------------------- | +| `make tx9` | Build `./bin/tx9` with the `VERSION` ldflag (`dev` by default) | +| `make check` | Full local gate: `syntax` + `lint` + `test` + `go-check` | +| `make syntax` | `bash -n` / `sh -n` / Python compile checks for shell and Python sources | +| `make lint` | ShellCheck over guest, provision, docker, and test shell scripts | +| `make test` | Static contract checks and guest-script regressions under `tests/` | +| `make go-check`| gofmt check, `go vet ./...`, and `go test ./...` | +| `make format` | Format all Go files with `gofmt -w` | +| `make dist` | Cross-compile linux/darwin amd64+arm64 binaries and `checksums.txt` into `dist/` | + +## Pull requests + +- Keep the diff focused, and run `make check` before opening a PR. +- Note the `make check` result in the PR body, and call out any test you could not run. diff --git a/README.md b/README.md index dc931a7..9ec2dcf 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,48 @@ For a stable HTTPS Executor origin and OAuth callbacks over a tailnet, see For host directories and NAS shares that should be visible inside an agent, see [Host mounts](docs/host-mounts.md). +## Install + +Prerequisites: + +- Linux or macOS (amd64 or arm64) with a running Docker daemon — `docker info` should succeed. Creating a box needs internet access for the first image build. +- To build from source: Go matching `go.mod` (currently Go 1.26). + +Install the latest release: + +```bash +curl -fsSL https://tx9.col-agents.com/install | sh +# installs to ~/.local/bin/tx9 (override with TX9_INSTALL_DIR) +``` + +Or with Go (reports version `dev`; use a release binary or `make tx9` for a stamped version): + +```bash +go install github.com/davis7dotsh/tx9@latest +``` + +Or build from source: + +```bash +git clone https://github.com/davis7dotsh/tx9.git +cd tx9 +make tx9 # writes ./bin/tx9 +./bin/tx9 +``` + +## Quickstart + +```bash +tx9 create # optional name: tx9 create my-box; first run builds the box image and can take a while +tx9 list # list boxes, status, and dashboard URLs +tx9 enter my-box # shell into the agent container +tx9 doctor my-box # health checks +tx9 open my-box # authenticated Executor dashboard URL +tx9 delete my-box # remove the box when done +``` + +Run `tx9` with no arguments for an overview of every box. See [Contributing](CONTRIBUTING.md) to build and test from source. + ## Model ```text @@ -261,6 +303,9 @@ disposable helper tests. The audit used an existing `ubuntu:24.04` image. `.depot/workflows/check.yml` runs the Go/guest and site checks through Depot CI for pushes to `main` and pull requests against any branch, including stacks. +`.github/workflows/check.yml` runs `gofmt`, `go vet`, `go build`, and +`go test ./...` on GitHub Actions for pushes to `main` and every pull request, +with no Docker daemon required. ## Releases