Skip to main content

Use Remote Configs

Remote configs let you share datamitsu configuration across multiple repositories. A team or organization can maintain a central configuration that individual projects inherit and extend.

Creating a Remote Config​

A remote config is a standard datamitsu config file hosted at an HTTPS URL. It exports getMinVersion() and getConfig() like any local config:

// https://config.myorg.com/datamitsu/base.js
function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      // organization-standard tools
    },
    tools: {
      ...config.tools,
      // organization-standard tool definitions
    },
    ignoreRules: [...config.ignoreRules, "vendor/**/*: *"],
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";

Host this file on any HTTPS server accessible to your team.

Using a Remote Config​

Reference remote configs by exporting a getRemoteConfigs() function from your local config:

/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// datamitsu.config.js
function getRemoteConfigs() {
  return [
    {
      url: "https://config.myorg.com/datamitsu/base.js",
      hash: "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(config) {
  // config already includes remote config changes
  return {
    ...config,
    // project-specific overrides
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";

Hash Verification​

Every remote config requires a SHA-256 hash. This is a strict security requirement: datamitsu refuses to load a remote config without a valid hash. Write it canonically — sha256: followed by 64 lowercase hex characters. A bare or uppercase value is accepted here and normalized to canonical, because this pin is routinely copied from a release page or a checksum file; every other hash pin in datamitsu.config accepts the canonical form only.

The publisher should hash the local file before uploading it and distribute that value through a reviewed release or change:

sha256sum base.js

Copy the published value into the hash field. Do not download unknown content merely to discover the value that will later be used to trust the same content. If you audit the hosted bytes manually, start with the expected hash and verify the download immediately:

EXPECTED_SHA256="a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
curl --fail --location --output /tmp/datamitsu-base.js \
  "https://config.myorg.com/datamitsu/base.js"
printf '%s  %s\n' "$EXPECTED_SHA256" /tmp/datamitsu-base.js | sha256sum --check -

When the remote config changes, update its reviewed hash in every consuming project.

Config Inheritance Chain​

Remote configs are resolved depth-first before the referencing config's getConfig() runs. Remote configs can themselves reference other remote configs, creating an inheritance chain:

Organization base config (remote)
  ↓ getRemoteConfigs()
Team-specific config (remote)
  ↓ getRemoteConfigs()
Project config (local datamitsu.config.js)

Each layer receives the accumulated configuration from all previous layers and can extend or override it.

Circular dependencies are detected and produce an error.

Wrapper Package Pattern​

For npm-based monorepos, you can distribute configuration as an npm package:

// @myorg/datamitsu-config/index.js
function getRemoteConfigs() {
  return [
    {
      url: "https://config.myorg.com/datamitsu/base.js",
      hash: "sha256:abc123...",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(config) {
  return {
    ...config,
    // organization-specific overrides on top of the remote base
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";

Projects use it via --before-config:

datamitsu check --before-config ./node_modules/@myorg/datamitsu-config/index.js

This pattern separates the shared configuration (the npm package) from the remote base config, allowing the remote base to be updated independently.

Caching​

Remote configs are cached locally to avoid network requests on every run:

  • Cache location: {store}/.remote-configs/
  • Cache validity is determined by hash match — if the cached content matches the expected SHA-256 hash, it is used without a network request
  • When the hash in your config changes (pointing to a new version), datamitsu fetches the updated content

Security​

Remote config loading includes several security measures:

  • SHA-256 hash verification is mandatory -- missing or mismatched hashes cause an error
  • HTTPS-to-HTTP redirects are rejected
  • Response size is limited to 10 MiB
  • Requests have a 30-second timeout

Skipping Remote Configs​

For offline development or testing, skip remote config resolution:

# Skip remote configs during verify-all
datamitsu devtools verify-all --no-remote

Updating Remote Configs​

When a remote config is updated, each consuming project needs to update its hash pin:

  1. Compute the new SHA-256 from the local release file
  2. Publish that exact file and its hash
  3. Update the hash field in each project's getRemoteConfigs() return value
  4. Commit the hash update

This explicit update step is intentional -- it ensures that config changes are reviewed and deployed deliberately, not automatically.