# Gizmo's announced v2 import path never shipped, and the install depends on the old capitalisation

> Gizmo is The New York Times' Go toolkit for building server and pubsub daemons, wrapped around go-kit, OpenCensus and cloud platform conventions. The page declares maintenance mode, and the dependency list, the module path and the Makefile all date from the period when that was announced.

**nytimes/gizmo** — GitHub describes it as A Microservice Toolkit from The New York Times. The repository metadata lists Go as its primary language. The metadata lists the Apache-2.0 license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/nytimes/gizmo
- Website: https://open.nytimes.com/introducing-gizmo-aa7ea463b208
- Stars: 3,769 · Forks: 224
- Language: Go
- License: Apache-2.0
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/nytimes-gizmo

## Maintenance mode, a 2020 release and a March 2026 commit

Three dates matter and they do not agree with each other.

The page states that as of late April 2021 Gizmo has been placed in maintenance mode. The most recent release is v1.3.6, titled Datadog exporter plus bug fixes, published 2020-08-25. Before it, v1.3.5 exposed PublishSettings in pubsub/gcp on 2019-12-20, and v1.3.4 properly logged panic messages in server/kit on 2019-11-12.

The last push to master is dated 2026-03-18, which is 201 days before this article's date and therefore past the six-month mark the site uses.

So the release line stopped in August 2020, the project announced in April 2021 that it would stop changing, and commits have continued on the branch since. Nothing on the page says what those commits are for, and the version numbers give a reader no way to pick up a fix: there is no tag to point a dependency at that includes the last two years of work.

## The v2 import path was announced as an intention and go.mod still says otherwise

There is a section devoted to the GitHub organisation rename, and it is the part of the page most likely to cost you an afternoon.

The install line is one command with a warning attached:

```bash
go get github.com/NYTimes/gizmo/...
```

The warning is about capitalisation. The organisation changed from NYTimes to nytimes on GitHub, and the page says the installation is unaffected as long as you use the proper casing NYTimes rather than nytimes. Then it describes the intended fix: migrating the import paths to match GitHub, which will be a breaking change, which will come with a major tag, moving from github.com/NYTimes/gizmo/server to github.com/nytimes/gizmo/v2/server so that nobody ends up with type mismatches across the two path forms.

None of that has happened. The module file declares:

```
module github.com/NYTimes/gizmo
```

No v2 suffix, the old casing, and a go directive of 1.12. So the breaking migration described as the plan is still the plan, and the workaround of deliberately using the wrong capitalisation is what the install depends on today.

## The test target cannot run unless a GOPATH-mode linter installs

The Makefile chains everything through linting. The default target is test, test depends on deps and pretest, pretest depends on lint, and lint begins by installing the linter outside module mode:

```bash
GO111MODULE=off go get golang.org/x/lint/golint
```

Then it loops over every Go file in the repository and runs the linter on each one with an exit-status flag, skipping generated protobuf files, the examples directory, and two named test files.

Two problems sit in that chain. Setting GO111MODULE=off puts the tool install back into the pre-module layout, in a repository that declares itself a module, and golint is a tool that has not been maintained for years. And because pretest gates test, a failure to install or run the linter stops the tests from running at all.

The test line itself is `go test -vet all ./...`, which runs every vet analyzer before the tests. The coverage target calls a shell script in the root with a coveralls flag.

## The pubsub section names two interfaces and the test package implements three

The pubsub package is described as holding two generic interfaces, publisher and subscriber, for publishing to queues and consuming from them. Four implementations follow, one per backend: Amazon SNS and SQS, Google Pub/Sub, Kafka topics, and plain HTTP.

Then the testing package is described as providing test implementations of three interfaces. The three are pubsub.Publisher, pubsub.MultiPublisher and pubsub.Subscriber.

So there is a MultiPublisher, and the section that introduces the package's interfaces does not mention it. Either the interface arrived after the documentation was written or it was never documented, and from a reader's side the difference is the same: to mock the interface you actually get back from a multi-target publish, you have to know it exists.

The examples for this package live under examples/, alongside examples for the servers and one for an internal-looking nyt/ directory.

## server/kit registers on five platforms and expects one

The kit package is the opinionated one, described as a server with fewer choices than the base server package. go-kit serves HTTP and JSON, gRPC serves HTTP2 and RPC, and monitoring, traces and metrics are registered automatically when the process detects App Engine, Cloud Run, Kubernetes Engine, Compute Engine or an AWS EC2 instance.

Two details in that list. The error reporting name and version come from the SERVICE_NAME and SERVICE_VERSION environment variables, which is the whole configuration surface for a service built on this package. And the last item in the same list is Go's 1.8 graceful HTTP shutdown, named by its Go version, in a module that declares go 1.12.

The platform list and the expectation do not match either. Five platforms are detected, including AWS EC2, and the same section says services using this package are expected to deploy to GCP. Logs go to stdout locally and directly to Stackdriver when running on Google Cloud.

## Three telemetry backends are wired in, through a tracing library Google has since replaced

The observe package provides metrics and tracing helpers through OpenCensus, and the kit package uses it to create a StackDriver exporter with what the page calls sane defaults. Three helper names are exported for platform detection: GoogleProjectID, IsGAE and IsCloudRun.

The module file shows how wide that surface became. There is a Stackdriver exporter for OpenCensus, an OpenCensus DataDog exporter pinned to a December 2019 commit, dd-trace-go as an indirect dependency, and the Prometheus client library. So a service gets a Google exporter by default and can also ship metrics to DataDog and Prometheus.

The tracing layer underneath is go.opencensus.io at v0.22.3, which is the generation of instrumentation that preceded OpenTelemetry. That single fact is the clearest summary of where this toolkit sits: the observability approach is one consolidation cycle behind, and the migration path is not described anywhere on the page.

The section also says the kit package uses observe, and soon SimpleServer will too. That is an unfinished intention left in the documentation.

## Two key sources for identity, one of them built for a runtime that no longer exists

The auth package deals with inbound tokens. It defines a PublicKeySource interface, which is meant to provide RSA public keys from JSON Web Key Sets, and a Verifier struct that composes key sources with custom decoders and verifier functions.

The GCP subpackage supplies two implementations of both interfaces, and the difference between them is a deployment story. The Identity source uses the instance identity JWT mechanism and is described as the preferred way to assert instance identity on Google Cloud. The IAM source uses Google's IAM services to sign and verify JSON web tokens, works outside Google Cloud, and is offered as a bridge for users moving from the first generation App Engine runtime to the second, where Identity tokens are not available.

That bridge exists because of a runtime split that has since been closed. A reader today has two sources where one platform now offers one, and the page gives no guidance on which to pick.

There is also an Authenticator in the same package, which wraps a Google identity verifier with oauth2 credentials for a basic web sign-in flow. Support is the gizmo channel in the Gophers Slack workspace, and the logo is credited to the Go mascot by Renée French under a Creative Commons attribution licence.

## The examples are a separate module, which is why the linter skips them

The examples directory carries its own go.mod and its own go.sum, alongside a README and three subdirectories: nyt/, pubsub/ and servers/.

A nested module is excluded from the parent module's ./... pattern, so those examples are not built by go build ./... and not tested by go test -vet all ./.... The Makefile agrees: its lint loop filters out anything under examples.

That arrangement is deliberate and it has a cost. The examples are the only place on the page where the packages are shown being put together, and they are the part of the repository that a compiler will not check. Nothing in the build verifies that the reference implementations still compile against the current package APIs, which is the failure mode a maintenance-mode project with an unexecuted import path migration is most exposed to.

The root is otherwise plain: a LICENSE, a Makefile, a coverage script, a doc.go, a Travis configuration, and the six package directories the page describes.

## Conclusion

Gizmo fits a team that already runs Go services on Google Cloud and wants the conventions the Times used, rather than a team starting a new service today. The honest reason to read it is the shape of the decisions, not the code: a maintenance-mode notice from April 2021, a last release from August 2020, an import path migration that was announced and never carried out, and a build whose test target depends on installing a linter outside module mode. Check three things before you depend on it. Whether the module path still resolves for your case, since the instructions require the old capitalisation. Which telemetry backend you want, because three are wired in. And whether you can build at all, because the Makefile's test target cannot run unless its lint step succeeds.

## FAQ

### Is the Gizmo microservice toolkit still maintained?

The page states that as of late April 2021 Gizmo has been placed in maintenance mode. The most recent release is v1.3.6 from 2020-08-25, and the last push to master is dated 2026-03-18.

### How do I install Gizmo?

With go get github.com/NYTimes/gizmo/... . The page insists on the capitalisation: use NYTimes rather than nytimes even though the GitHub organisation now uses the lowercase form.

### Did the Gizmo v2 import path change ever happen?

No. The page announces the intention to move from github.com/NYTimes/gizmo/server to github.com/nytimes/gizmo/v2/server with a major tag, but go.mod still declares the module as github.com/NYTimes/gizmo with no version suffix.

### Which pubsub backends does Gizmo support?

Four implementations of its publisher and subscriber interfaces: Amazon SNS and SQS through pubsub/aws, Google Pub/Sub through pubsub/gcp, Kafka topics through pubsub/kafka and plain HTTP through pubsub/http. A pubsubtest package provides test doubles for Publisher, MultiPublisher and Subscriber.

### What does a service built on Gizmo's server/kit package need?

A Google Cloud deployment, by the package's own statement. It registers monitoring, traces and metrics automatically on App Engine, Cloud Run, Kubernetes Engine, Compute Engine or AWS EC2, writes logs to stdout locally or to Stackdriver on Google Cloud, and takes the error reporting name and version from the SERVICE_NAME and SERVICE_VERSION environment variables.

### Which telemetry backends does Gizmo wire up?

Three: a StackDriver exporter for OpenCensus as the default with what the page calls sane defaults, a DataDog OpenCensus exporter pinned to a December 2019 commit, and the Prometheus client library. The underlying tracing library is go.opencensus.io.

## Sources

- [Official documentation](https://open.nytimes.com/introducing-gizmo-aa7ea463b208)
- [Official README](https://github.com/nytimes/gizmo#readme)
- [Project repository](https://github.com/nytimes/gizmo)
- [Release notes](https://github.com/nytimes/gizmo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nytimes-gizmo