Safety and Opt-out

updater.zig is designed with user privacy and control as primary concerns. This page explains all safety features and opt-out mechanisms.

Design Principles

1. Zero surprise networking: No network requests without explicit opt-in
2. Never fail builds: Update checks never cause build failures
3. User control: Multiple ways to disable checking
4. Nested dependency safe: Parent projects can control child dependencies

Global Opt-out

Environment Variable

Set ZIG_UPDATE_CHECK_DISABLE to disable all update checking:

# Linux/macOS
export ZIG_UPDATE_CHECK_DISABLE=1

# Windows (PowerShell)
$env:ZIG_UPDATE_CHECK_DISABLE = "1"

# Windows (CMD)
set ZIG_UPDATE_CHECK_DISABLE=1

This disables:

• Build-time checks
• Runtime foreground checks
• Runtime background checks
• Checks from all dependencies (nested dependency safe)

Checking Status

if (updater.isGloballyDisabled()) {
    std.debug.print("Update checking is disabled\n", .{});
    return;
}

CI Detection

Common CI environments are automatically detected:

Environment Variable	CI System
CI	Generic CI indicator
CONTINUOUS_INTEGRATION	Generic CI indicator
GITHUB_ACTIONS	GitHub Actions
GITLAB_CI	GitLab CI
CIRCLECI	CircleCI
TRAVIS	Travis CI
JENKINS_URL	Jenkins
BUILDKITE	Buildkite
DRONE	Drone CI
AZURE_PIPELINES	Azure Pipelines

Checking CI Status

if (updater.isCI()) {
    std.debug.print("Running in CI environment\n", .{});
    return;
}

Configuration-based Disabling

Disable in Config

const result = try updater.checkForUpdates(allocator, .{
    .enabled = false,  // Explicitly disable
    .provider = updater.providers.github,
    .owner = "username",
    .repo = "project",
    .current_version = "1.0.0",
});

Build Options

const updater_dep = b.dependency("updater", .{
    .target = target,
    .optimize = optimize,
    .enable_update_checker = false,  // Disable at build time
});

Or via command line:

zig build -Denable_update_checker=false

For Library Authors

If you are writing a library that uses updater.zig:

1. Make it Optional

pub fn build(b: *std.Build) void {
    // Default to false for libraries
    const enable_updates = b.option(
        bool,
        "enable_library_updates",
        "Enable checking for library updates",
    ) orelse false;

    if (enable_updates) {
        // Only add update checking if explicitly enabled
        updater.build_integration.addUpdateCheck(b, .{
            .owner = "library-author",
            .repo = "mylib",
            .current_version = "1.0.0",
        });
    }
}

2. Document Network Behavior

Always document:

• When network requests are made
• What data is sent
• How users can disable it

3. Respect User Preferences

Always check the global opt-out:

if (updater.isGloballyDisabled()) {
    return;  // Respect user's choice
}

Network Behavior

What updater.zig sends

• HTTP GET request to the provider's API
• User-Agent header (configurable)
• Accept header for JSON

What updater.zig receives

• Release/tag information from the API
• Version number
• Release URL

What updater.zig does NOT do

• Track users
• Send identifying information
• Make requests without explicit configuration
• Store any data

Error Handling

Update checks are designed to be non-fatal:

Build-time

Build-time checks never fail the build:

warning: [updater.zig] Update check failed: ConnectionFailed
Build succeeded.

Runtime

Runtime checks return errors that should be handled gracefully:

const result = updater.checkForUpdates(allocator, config) catch |err| {
    // Log but don't crash
    std.log.warn("Update check failed: {}", .{err});
    return;
};

Nested Dependency Safety

When your project depends on a library that uses updater.zig:

your-project/
├── build.zig
└── deps/
    └── some-library/  (uses updater.zig internally)

Setting ZIG_UPDATE_CHECK_DISABLE=1 will disable update checks in:

• Your project
• some-library
• Any transitive dependencies

This ensures users have complete control over network behavior.

Recommendations

For Application Developers

1. Enable update checking for your main application
2. Disable it in CI environments (automatic)
3. Document the feature for your users
4. Respect the global opt-out

For Library Developers

1. Default to disabled
2. Require explicit opt-in
3. Document network behavior clearly
4. Always check isGloballyDisabled()

For End Users

1. Use ZIG_UPDATE_CHECK_DISABLE=1 to opt out globally
2. Check library documentation for per-library options
3. Review build options for update-related settings

Next Steps

• Configuration - Full configuration reference
• Custom Providers - Self-hosted servers