feat: include commit reference in stack info for each ENSNode service

.github/workflows/release.yml

@@ -155,6 +155,8 @@ jobs:
             type=semver,pattern={{version}},value=${{ matrix.apps.version }}
             type=ref,event=branch
             type=sha
+          build_args: |
+            GIT_COMMIT=${{ github.sha }}
 
   build-lambdas:
     name: ${{ matrix.lambdas.name }} ${{ matrix.lambdas.version }}

.github/workflows/release_preview.yml

@@ -247,6 +247,8 @@ jobs:
             type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}
             type=raw,value=${{ needs.validate-and-prepare.outputs.docker-tag-base }}-${{ needs.validate-and-prepare.outputs.commit-sha }}
             type=sha
+          build_args: |
+            GIT_COMMIT=${{ github.sha }}
 
   build-and-publish-lambdas:
     name: Build & Publish Preview Lambdas

.github/workflows/release_snapshot.yml

@@ -122,6 +122,8 @@ jobs:
             type=raw,value=next
             type=raw,value=${{ steps.snapshot-tag.outputs.tag }}
             type=sha
+          build_args: |
+            GIT_COMMIT=${{ github.sha }}
 
   build-and-publish-lambdas:
     name: Build & Publish Snapshot Lambdas

apps/ensapi/Dockerfile

@@ -14,6 +14,12 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
 FROM deps AS runner
 WORKDIR /app/apps/ensapi
 ENV NODE_ENV=production
+# Read the build arg
+ARG GIT_COMMIT
+# Set the GIT_COMMIT as an environment variable for the app runtime.
+ENV GIT_COMMIT=$GIT_COMMIT
+# Attach the GIT_COMMIT as a label for the image, so it can be inspected later.
+LABEL org.opencontainers.image.revision=$GIT_COMMIT
 EXPOSE 4334
 
 CMD ["pnpm", "start"]

apps/ensapi/src/config/environment.ts

@@ -1,5 +1,6 @@
 import type {
   EnsDbEnvironment,
+  GitEnvironment,
   LogLevelEnvironment,
   PortEnvironment,
   ReferralProgramEditionsEnvironment,
@@ -14,7 +15,8 @@ import type {
  * their state in `process.env`. This interface is intended to be the source type which then gets
  * mapped/parsed into a structured configuration object like `EnsApiConfig`.
  */
-export type EnsApiEnvironment = EnsDbEnvironment &
+export type EnsApiEnvironment = GitEnvironment &
+  EnsDbEnvironment &
   RpcEnvironment &
   PortEnvironment &
   LogLevelEnvironment &

apps/ensapi/src/lib/version-info.ts

@@ -5,6 +5,16 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import type { EnsApiVersionInfo } from "@ensnode/ensnode-sdk";
+import { buildCommitRef } from "@ensnode/ensnode-sdk/internal";
+
+import type { EnsApiEnvironment } from "@/config/environment";
+
+/**
+ * Get ENSApi codebase commit reference
+ */
+export function getEnsApiCommitRef(): string | undefined {
+  return buildCommitRef(process.env satisfies EnsApiEnvironment);
+}
 
 /**
  * Get ENS API version
@@ -101,6 +111,7 @@ function getPackageVersionFromPnpmStore(pnpmDir: string, packageName: string): s
 }
 
 export const ensApiVersionInfo = {
+  commit: getEnsApiCommitRef(),
   ensApi: getEnsApiVersion(),
   ensNormalize: getPackageVersion("@adraffy/ens-normalize"),
 } as const satisfies EnsApiVersionInfo;

apps/ensindexer/Dockerfile

@@ -14,6 +14,12 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
 FROM deps AS runner
 WORKDIR /app/apps/ensindexer
 ENV NODE_ENV=production
+# Read the build arg
+ARG GIT_COMMIT
+# Set the GIT_COMMIT as an environment variable for the app runtime.
+ENV GIT_COMMIT=$GIT_COMMIT
+# Attach the GIT_COMMIT as a label for the image, so it can be inspected later.
+LABEL org.opencontainers.image.revision=$GIT_COMMIT
 EXPOSE 42069
 
 CMD ["pnpm", "start"]

apps/ensindexer/src/config/environment.ts

@@ -1,4 +1,8 @@
-import type { EnsDbEnvironment, RpcEnvironment } from "@ensnode/ensnode-sdk/internal";
+import type {
+  EnsDbEnvironment,
+  GitEnvironment,
+  RpcEnvironment,
+} from "@ensnode/ensnode-sdk/internal";
 
 /**
  * Represents the raw, unvalidated environment variables for the ENSIndexer application.
@@ -7,7 +11,8 @@ import type { EnsDbEnvironment, RpcEnvironment } from "@ensnode/ensnode-sdk/inte
  * their state in `process.env`. This interface is intended to be the source type which then gets
  * mapped/parsed into a structured configuration object like `ENSIndexerConfig`.
  */
-export type ENSIndexerEnvironment = EnsDbEnvironment &
+export type ENSIndexerEnvironment = GitEnvironment &
+  EnsDbEnvironment &
   RpcEnvironment & {
     NAMESPACE?: string;
     PLUGINS?: string;

apps/ensindexer/src/lib/public-config-builder/public-config-builder.test.ts

@@ -27,6 +27,7 @@ vi.mock("@/config", () => ({
 vi.mock("@/lib/version-info", () => ({
   getEnsIndexerVersion: vi.fn(),
   getPackageVersion: vi.fn(),
+  getEnsIndexerCommitRef: vi.fn(),
 }));
 
 // Mock the SDK validation functions
@@ -47,18 +48,24 @@ import {
   validateEnsIndexerVersionInfo,
 } from "@ensnode/ensnode-sdk";
 
-import { getEnsIndexerVersion, getPackageVersion } from "@/lib/version-info";
+import {
+  getEnsIndexerCommitRef,
+  getEnsIndexerVersion,
+  getPackageVersion,
+} from "@/lib/version-info";
 
 // Test fixtures
 const mockEnsRainbowConfig: EnsRainbowPublicConfig = {
   serverLabelSet: { labelSetId: "subgraph", highestLabelSetVersion: 0 },
   versionInfo: {
+    commit: "a26a979f06f52ef0e40e69da1052e190240db29b",
     ensRainbow: "1.0.0",
   },
 };
 
 const mockVersionInfo: EnsIndexerVersionInfo = {
   ponder: "0.9.0",
+  commit: "a26a979f06f52ef0e40e69da1052e190240db29b",
   ensDb: "1.0.0",
   ensIndexer: "1.0.0",
   ensNormalize: "1.10.0",
@@ -83,6 +90,7 @@ function createMockPublicConfig(overrides: Partial<EnsIndexerPublicConfig> = {})
 function setupStandardMocks() {
   vi.mocked(getEnsIndexerVersion).mockReturnValue("1.0.0");
   vi.mocked(getPackageVersion).mockReturnValue("0.9.0");
+  vi.mocked(getEnsIndexerCommitRef).mockReturnValue("a26a979f06f52ef0e40e69da1052e190240db29b");
   vi.mocked(validateEnsIndexerVersionInfo).mockReturnValue(mockVersionInfo);
 }
 
@@ -115,6 +123,7 @@ describe("PublicConfigBuilder", () => {
 
       expect(validateEnsIndexerVersionInfo).toHaveBeenCalledWith({
         ponder: "0.9.0",
+        commit: "a26a979f06f52ef0e40e69da1052e190240db29b",
         ensDb: "1.0.0",
         ensIndexer: "1.0.0",
         ensNormalize: "0.9.0",
@@ -182,6 +191,7 @@ describe("PublicConfigBuilder", () => {
 
       const customVersionInfo: EnsIndexerVersionInfo = {
         ponder: "1.0.0",
+        commit: "a26a979f06f52ef0e40e69da1052e190240db29b",
         ensDb: "2.0.0",
         ensIndexer: "2.0.0",
         ensNormalize: "1.10.0",
@@ -210,6 +220,7 @@ describe("PublicConfigBuilder", () => {
       const customEnsRainbowConfig: EnsRainbowPublicConfig = {
         serverLabelSet: { labelSetId: "custom", highestLabelSetVersion: 1 },
         versionInfo: {
+          commit: "a26a979f06f52ef0e40e69da1052e190240db29b",
           ensRainbow: "1.0.0",
         },
       };

apps/ensindexer/src/lib/public-config-builder/public-config-builder.ts

@@ -8,7 +8,11 @@ import {
 } from "@ensnode/ensnode-sdk";
 import type { EnsRainbow } from "@ensnode/ensrainbow-sdk";
 
-import { getEnsIndexerVersion, getPackageVersion } from "@/lib/version-info";
+import {
+  getEnsIndexerCommitRef,
+  getEnsIndexerVersion,
+  getPackageVersion,
+} from "@/lib/version-info";
 
 export class PublicConfigBuilder {
   /**
@@ -84,6 +88,7 @@ export class PublicConfigBuilder {
 
     return validateEnsIndexerVersionInfo({
       ponder: getPackageVersion("ponder"),
+      commit: getEnsIndexerCommitRef(),
       ensDb: ensDbVersion,
       ensIndexer: ensIndexerVersion,
       ensNormalize: getPackageVersion("@adraffy/ens-normalize"),

apps/ensindexer/src/lib/version-info.ts

@@ -4,8 +4,18 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { buildCommitRef } from "@ensnode/ensnode-sdk/internal";
+
+import type { ENSIndexerEnvironment } from "@/config/environment";
 import { logger } from "@/lib/logger";
 
+/**
+ * Get ENSIndexer codebase commit reference
+ */
+export function getEnsIndexerCommitRef(): string | undefined {
+  return buildCommitRef(process.env satisfies ENSIndexerEnvironment);
+}
+
 /**
  * Get ENSIndexer version
  */

apps/ensrainbow/Dockerfile

@@ -36,6 +36,12 @@ RUN chmod +x /app/apps/ensrainbow/scripts/download-prebuilt-database.sh
 
 # Set environment variables
 ENV NODE_ENV=production
+# Read the build arg
+ARG GIT_COMMIT
+# Set the GIT_COMMIT as an environment variable for the app runtime.
+ENV GIT_COMMIT=$GIT_COMMIT
+# Attach the GIT_COMMIT as a label for the image, so it can be inspected later.
+LABEL org.opencontainers.image.revision=$GIT_COMMIT
 # PORT is consumed by the entrypoint command, defaulting to 3223 if not set at runtime.
 # DB_SCHEMA_VERSION, LABEL_SET_ID, LABEL_SET_VERSION must be provided at runtime to the entrypoint.
 

apps/ensrainbow/src/config/config.schema.test.ts

@@ -397,7 +397,7 @@ describe("buildEnsRainbowPublicConfig", () => {
   it("returns a valid ENSRainbow public config with correct structure", () => {
     const result = buildEnsRainbowPublicConfig(dbConfig);
 
-    expect(result).toStrictEqual({
+    expect(result).toMatchObject({
       serverLabelSet: dbConfig.serverLabelSet,
       versionInfo: {
         ensRainbow: packageJson.version,

apps/ensrainbow/src/config/environment.ts

@@ -1,9 +1,14 @@
-import type { LogLevelEnvironment, PortEnvironment } from "@ensnode/ensnode-sdk/internal";
+import type {
+  GitEnvironment,
+  LogLevelEnvironment,
+  PortEnvironment,
+} from "@ensnode/ensnode-sdk/internal";
 
 /**
  * Raw, unvalidated environment variables for ENSRainbow.
  */
-export type ENSRainbowEnvironment = PortEnvironment &
+export type ENSRainbowEnvironment = GitEnvironment &
+  PortEnvironment &
   LogLevelEnvironment & {
     DATA_DIR?: string;
     DB_SCHEMA_VERSION?: string;

apps/ensrainbow/src/config/public.ts

@@ -1,16 +1,34 @@
 import packageJson from "@/../package.json" with { type: "json" };
 
 import type { EnsRainbowServerLabelSet, EnsRainbowVersionInfo } from "@ensnode/ensnode-sdk";
+import { buildCommitRef } from "@ensnode/ensnode-sdk/internal";
 import type { EnsRainbow } from "@ensnode/ensrainbow-sdk";
 
+import type { ENSRainbowEnvironment } from "@/config/environment";
+
 import type { DbConfig } from "./types";
 
+/**
+ * Get ENSRainbow codebase commit reference
+ */
+export function getEnsRainbowCommitRef(): string | undefined {
+  return buildCommitRef(process.env satisfies ENSRainbowEnvironment);
+}
+
+/**
+ * Get ENSRainbow version
+ */
+function getEnsRainbowVersion(): string {
+  return packageJson.version;
+}
+
 /** Builds public config from a label set (CLI/env before DB open, or from DB after open). */
 export function buildEnsRainbowPublicConfigFromLabelSet(
   serverLabelSet: EnsRainbowServerLabelSet,
 ): EnsRainbow.ENSRainbowPublicConfig {
   const versionInfo = {
-    ensRainbow: packageJson.version,
+    commit: getEnsRainbowCommitRef(),
+    ensRainbow: getEnsRainbowVersion(),
   } satisfies EnsRainbowVersionInfo;
 
   return {

docker/README.md

@@ -21,6 +21,24 @@ All commands are run from the **monorepo root**.
 > docker compose -f docker/docker-compose.yml config
 > ```
 
+## Build-time environment
+
+The ENSNode service images (`ensindexer`, `ensapi`, `ensrainbow`) bake a `GIT_COMMIT` value into their public config's `versionInfo.commit`. When building these docker images, you can pass the `GIT_COMMIT` build arg in order to "bake in" the commit reference into each docker image.
+
+### Docker compose
+
+```bash
+GIT_COMMIT=$(git rev-parse HEAD) docker compose -f docker/docker-compose.yml up --build
+```
+
+### Docker build
+
+```bash
+docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -f apps/ensapi/Dockerfile -t ghcr.io/namehash/ensnode/ensapi:latest .
+docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -f apps/ensindexer/Dockerfile -t ghcr.io/namehash/ensnode/ensindexer:latest .
+docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -f apps/ensrainbow/Dockerfile -t ghcr.io/namehash/ensnode/ensrainbow:latest .
+```
+
 ## Use cases
 
 ### Mainnet / Sepolia

docker/services/ensapi.yml

@@ -5,6 +5,8 @@ services:
     build:
       dockerfile: ./apps/ensapi/Dockerfile
       context: ../..
+      args:
+        GIT_COMMIT: ${GIT_COMMIT}
     ports:
       - "4334:4334"
     healthcheck:

docker/services/ensindexer.yml

@@ -5,6 +5,8 @@ services:
     build:
       dockerfile: ./apps/ensindexer/Dockerfile
       context: ../..
+      args:
+        GIT_COMMIT: ${GIT_COMMIT}
     ports:
       - "42069:42069"
     healthcheck:

docker/services/ensrainbow.yml

@@ -5,6 +5,8 @@ services:
     build:
       dockerfile: ./apps/ensrainbow/Dockerfile
       context: ../..
+      args:
+        GIT_COMMIT: ${GIT_COMMIT}
     ports:
       - "3223:3223"
     volumes:

docs/ensnode.io/ensapi-openapi.json

@@ -821,6 +821,7 @@
                                 "versionInfo": {
                                   "type": "object",
                                   "properties": {
+                                    "commit": { "type": "string", "minLength": 1 },
                                     "ensRainbow": { "type": "string", "minLength": 1 }
                                   },
                                   "required": ["ensRainbow"]
@@ -860,6 +861,7 @@
                               "type": "object",
                               "properties": {
                                 "ponder": { "type": "string", "minLength": 1 },
+                                "commit": { "type": "string", "minLength": 1 },
                                 "ensDb": { "type": "string", "minLength": 1 },
                                 "ensIndexer": { "type": "string", "minLength": 1 },
                                 "ensNormalize": { "type": "string", "minLength": 1 }
@@ -896,7 +898,10 @@
                             },
                             "versionInfo": {
                               "type": "object",
-                              "properties": { "ensRainbow": { "type": "string", "minLength": 1 } },
+                              "properties": {
+                                "commit": { "type": "string", "minLength": 1 },
+                                "ensRainbow": { "type": "string", "minLength": 1 }
+                              },
                               "required": ["ensRainbow"]
                             }
                           },
@@ -931,6 +936,7 @@
                                     "versionInfo": {
                                       "type": "object",
                                       "properties": {
+                                        "commit": { "type": "string", "minLength": 1 },
                                         "ensRainbow": { "type": "string", "minLength": 1 }
                                       },
                                       "required": ["ensRainbow"]
@@ -970,6 +976,7 @@
                                   "type": "object",
                                   "properties": {
                                     "ponder": { "type": "string", "minLength": 1 },
+                                    "commit": { "type": "string", "minLength": 1 },
                                     "ensDb": { "type": "string", "minLength": 1 },
                                     "ensIndexer": { "type": "string", "minLength": 1 },
                                     "ensNormalize": { "type": "string", "minLength": 1 }
@@ -1020,6 +1027,7 @@
                             "versionInfo": {
                               "type": "object",
                               "properties": {
+                                "commit": { "type": "string", "minLength": 1 },
                                 "ensApi": { "type": "string", "minLength": 1 },
                                 "ensNormalize": { "type": "string", "minLength": 1 }
                               },