Merge remote-tracking branch 'origin/next' into api-sensitive-data-scrubber

tests/Unit/ApplicationDeploymentRailpackConfigTest.php

@@ -0,0 +1,249 @@
+<?php
+
+use App\Exceptions\DeploymentException;
+use App\Jobs\ApplicationDeploymentJob;
+use App\Models\Application;
+use Illuminate\Support\Collection;
+use Tests\TestCase;
+
+uses(TestCase::class);
+
+class TestableRailpackDeploymentJob extends ApplicationDeploymentJob
+{
+    public array $recordedCommands = [];
+
+    public function __construct() {}
+
+    public function execute_remote_command(...$commands)
+    {
+        $this->recordedCommands[] = $commands;
+    }
+}
+
+function makeRailpackDeploymentJob(array $applicationAttributes = [], array $savedOutputs = []): array
+{
+    $job = new TestableRailpackDeploymentJob;
+    $reflection = new ReflectionClass(ApplicationDeploymentJob::class);
+
+    $application = new Application($applicationAttributes);
+
+    foreach ([
+        'application' => $application,
+        'workdir' => '/artifacts/test-app',
+        'deployment_uuid' => 'deployment-uuid',
+        'saved_outputs' => new Collection($savedOutputs),
+        'env_railpack_args' => "--env 'RAILPACK_NODE_VERSION=22'",
+        'force_rebuild' => false,
+        'addHosts' => '',
+        'secrets_hash_key' => 'testing-app-key',
+    ] as $property => $value) {
+        $reflectionProperty = $reflection->getProperty($property);
+        $reflectionProperty->setAccessible(true);
+        $reflectionProperty->setValue($job, $value);
+    }
+
+    return [$job, $reflection];
+}
+
+function invokeRailpackMethod(object $job, ReflectionClass $reflection, string $method, array $arguments = []): mixed
+{
+    $reflectionMethod = $reflection->getMethod($method);
+    $reflectionMethod->setAccessible(true);
+
+    return $reflectionMethod->invokeArgs($job, $arguments);
+}
+
+it('deep merges repository railpack config with coolify overrides', function () {
+    $repositoryConfigJson = json_encode([
+        '$schema' => 'https://schema.railpack.com',
+        'packages' => [
+            'node' => '20',
+        ],
+        'steps' => [
+            'build' => [
+                'inputs' => [['step' => 'install']],
+                'commands' => ['npm run build'],
+            ],
+        ],
+        'deploy' => [
+            'variables' => [
+                'NODE_ENV' => 'production',
+            ],
+            'startCommand' => 'node index.js',
+        ],
+    ], JSON_THROW_ON_ERROR);
+
+    [$job, $reflection] = makeRailpackDeploymentJob(
+        [
+            'install_command' => 'npm ci',
+            'build_command' => 'npm run build:prod',
+            'start_command' => 'node server.js',
+        ],
+        [
+            'railpack_config_exists' => 'exists',
+            'railpack_repository_config' => $repositoryConfigJson,
+        ],
+    );
+
+    $repositoryConfig = invokeRailpackMethod(
+        $job,
+        $reflection,
+        'decode_railpack_config',
+        [$repositoryConfigJson, 'repository railpack.json'],
+    );
+    $overrides = [
+        'deploy' => [
+            'variables' => [
+                'APP_ENV' => 'production',
+            ],
+        ],
+        'packages' => [
+            'python' => '3.13',
+        ],
+    ];
+    $generatedConfig = invokeRailpackMethod($job, $reflection, 'merge_railpack_config', [$repositoryConfig, $overrides]);
+
+    expect($generatedConfig)->toMatchArray([
+        '$schema' => 'https://schema.railpack.com',
+        'packages' => [
+            'node' => '20',
+            'python' => '3.13',
+        ],
+        'steps' => [
+            'build' => [
+                'inputs' => [['step' => 'install']],
+                'commands' => ['npm run build'],
+            ],
+        ],
+        'deploy' => [
+            'variables' => [
+                'NODE_ENV' => 'production',
+                'APP_ENV' => 'production',
+            ],
+            'startCommand' => 'node index.js',
+        ],
+    ]);
+});
+
+it('writes a generated railpack config file when repository config exists', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob(
+        ['build_command' => 'npm run build'],
+        [
+            'railpack_config_exists' => 'exists',
+            'railpack_repository_config' => json_encode([
+                '$schema' => 'https://schema.railpack.com',
+                'steps' => [
+                    'build' => [
+                        'commands' => ['npm run build'],
+                    ],
+                ],
+            ], JSON_THROW_ON_ERROR),
+        ],
+    );
+
+    $configPath = invokeRailpackMethod($job, $reflection, 'generate_railpack_config_file');
+
+    expect($configPath)->toBe('.coolify/railpack.generated.json');
+    expect($job->recordedCommands)->toHaveCount(3);
+});
+
+it('does not generate a railpack config file for command overrides alone', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob([
+        'install_command' => 'npm ci',
+        'build_command' => 'npm run build',
+        'start_command' => 'node server.js',
+    ]);
+
+    $configPath = invokeRailpackMethod($job, $reflection, 'generate_railpack_config_file');
+
+    expect($configPath)->toBeNull();
+    expect($job->recordedCommands)->toHaveCount(1);
+});
+
+it('fails fast when repository railpack config is invalid json', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob(
+        ['build_command' => 'npm run build'],
+        [
+            'railpack_config_exists' => 'exists',
+            'railpack_repository_config' => '{"steps":{"build":',
+        ],
+    );
+
+    expect(fn () => invokeRailpackMethod($job, $reflection, 'generate_railpack_config_file'))
+        ->toThrow(DeploymentException::class, 'Invalid repository railpack.json');
+});
+
+it('builds railpack prepare command using railpack env for install and cli flags for build/start overrides', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob(
+        [
+            'install_command' => 'npm ci',
+            'build_command' => 'npm run build',
+            'start_command' => 'node server.js',
+        ],
+    );
+    $envRailpackArgsProperty = $reflection->getProperty('env_railpack_args');
+    $envRailpackArgsProperty->setAccessible(true);
+    $envRailpackArgsProperty->setValue($job, "--env 'RAILPACK_NODE_VERSION=22' --env 'RAILPACK_INSTALL_CMD=npm ci'");
+
+    $command = invokeRailpackMethod(
+        $job,
+        $reflection,
+        'railpack_prepare_command',
+        ['.coolify/railpack.generated.json'],
+    );
+
+    expect($command)->toContain('railpack prepare');
+    expect($command)->toContain("--env 'RAILPACK_NODE_VERSION=22'");
+    expect($command)->toContain("--env 'RAILPACK_INSTALL_CMD=npm ci'");
+    expect($command)->toContain('--build-cmd '.escapeshellarg('npm run build'));
+    expect($command)->toContain('--start-cmd '.escapeshellarg('node server.js'));
+    expect($command)->toContain('--config-file '.escapeshellarg('.coolify/railpack.generated.json'));
+    expect($command)->toContain('--plan-out /artifacts/railpack-plan.json /artifacts/test-app');
+    expect($command)->not->toContain("--env 'RAILPACK_BUILD_CMD=");
+    expect($command)->not->toContain("--env 'RAILPACK_START_CMD=");
+    expect($command)->not->toContain('RAILPACK_BUILD_CMD=');
+    expect($command)->not->toContain('RAILPACK_START_CMD=');
+});
+
+it('fails fast when docker buildx is unavailable for railpack builds', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob();
+
+    $dockerBuildxAvailableProperty = $reflection->getProperty('dockerBuildxAvailable');
+    $dockerBuildxAvailableProperty->setAccessible(true);
+    $dockerBuildxAvailableProperty->setValue($job, false);
+
+    expect(fn () => invokeRailpackMethod($job, $reflection, 'ensure_docker_buildx_available_for_railpack'))
+        ->toThrow(DeploymentException::class, 'Railpack deployments require the Docker buildx CLI plugin');
+});
+
+it('builds railpack docker command with matching env and secret flags for all railpack variables', function () {
+    [$job, $reflection] = makeRailpackDeploymentJob([
+        'uuid' => 'application-uuid',
+    ]);
+
+    $command = invokeRailpackMethod(
+        $job,
+        $reflection,
+        'railpack_build_command',
+        [
+            'coollabsio/coolify:test',
+            collect([
+                'RAILPACK_NODE_VERSION' => '22',
+                'RAILPACK_INSTALL_CMD' => 'npm ci && npm run postinstall',
+                'RAILPACK_DEPLOY_APT_PACKAGES' => 'curl wget',
+                'SECRET_JSON' => '{"token":"abc"}',
+            ]),
+        ],
+    );
+
+    expect($command)->toContain("env 'RAILPACK_NODE_VERSION=22'");
+    expect($command)->toContain("'RAILPACK_INSTALL_CMD=npm ci && npm run postinstall'");
+    expect($command)->toContain("'RAILPACK_DEPLOY_APT_PACKAGES=curl wget'");
+    expect($command)->toContain("'SECRET_JSON={\"token\":\"abc\"}'");
+    expect($command)->toContain("--secret 'id=RAILPACK_NODE_VERSION,env=RAILPACK_NODE_VERSION'");
+    expect($command)->toContain("--secret 'id=RAILPACK_INSTALL_CMD,env=RAILPACK_INSTALL_CMD'");
+    expect($command)->toContain("--secret 'id=RAILPACK_DEPLOY_APT_PACKAGES,env=RAILPACK_DEPLOY_APT_PACKAGES'");
+    expect($command)->toContain("--secret 'id=SECRET_JSON,env=SECRET_JSON'");
+    expect($command)->toContain(' --build-arg secrets-hash=');
+    expect($command)->toContain('--build-arg BUILDKIT_SYNTAX="ghcr.io/railwayapp/railpack-frontend:v'.config('constants.coolify.railpack_version').'"');
+});

tests/Unit/ApplicationDeploymentRailpackEnvParityTest.php

@@ -0,0 +1,267 @@
+<?php
+
+use App\Jobs\ApplicationDeploymentJob;
+use App\Models\Application;
+use App\Models\EnvironmentVariable;
+use App\Models\Server;
+
+it('generates escaped railpack env args from resolved values and includes install command', function () {
+    $application = Mockery::mock(Application::class);
+    $application->shouldReceive('getAttribute')->with('install_command')->andReturn('npm ci && npm run postinstall');
+
+    $nodeVersion = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $nodeVersion->forceFill([
+        'key' => 'RAILPACK_NODE_VERSION',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $nodeVersion->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn('22');
+
+    $literalValue = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $literalValue->forceFill([
+        'key' => 'RAILPACK_CUSTOM_FLAG',
+        'is_literal' => true,
+        'is_multiline' => false,
+    ]);
+    $literalValue->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn("'hello world'");
+
+    $jsonValue = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $jsonValue->forceFill([
+        'key' => 'RAILPACK_JSON',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $jsonValue->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn('{"token":"abc"}');
+
+    $nullValue = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $nullValue->forceFill([
+        'key' => 'RAILPACK_NULL',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $nullValue->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn(null);
+
+    $envQuery = Mockery::mock();
+    $envQuery->shouldReceive('withoutBuildpackControlVariables')->once()->andReturnSelf();
+    $envQuery->shouldReceive('where')->with('is_buildtime', true)->once()->andReturnSelf();
+    $envQuery->shouldReceive('get')->once()->andReturn(collect([]));
+    $application->shouldReceive('environment_variables')->once()->andReturn($envQuery);
+
+    $railpackQuery = Mockery::mock();
+    $railpackQuery->shouldReceive('get')->once()->andReturn(collect([$nodeVersion, $literalValue, $jsonValue, $nullValue]));
+    $application->shouldReceive('railpack_environment_variables')->once()->andReturn($railpackQuery);
+
+    $job = Mockery::mock(ApplicationDeploymentJob::class)->makePartial();
+    $job->shouldAllowMockingProtectedMethods();
+    $job->shouldReceive('generate_coolify_env_variables')->andReturn(collect([]));
+
+    $reflection = new ReflectionClass(ApplicationDeploymentJob::class);
+    $applicationProperty = $reflection->getProperty('application');
+    $applicationProperty->setAccessible(true);
+    $applicationProperty->setValue($job, $application);
+
+    $pullRequestProperty = $reflection->getProperty('pull_request_id');
+    $pullRequestProperty->setAccessible(true);
+    $pullRequestProperty->setValue($job, 0);
+
+    $mainServerProperty = $reflection->getProperty('mainServer');
+    $mainServerProperty->setAccessible(true);
+    $mainServerProperty->setValue($job, Mockery::mock(Server::class));
+
+    $method = $reflection->getMethod('generate_railpack_env_variables');
+    $method->setAccessible(true);
+    $variables = $method->invoke($job);
+
+    $envArgsProperty = $reflection->getProperty('env_railpack_args');
+    $envArgsProperty->setAccessible(true);
+    $envArgs = $envArgsProperty->getValue($job);
+
+    expect($variables->all())->toBe([
+        'RAILPACK_NODE_VERSION' => '22',
+        'RAILPACK_CUSTOM_FLAG' => 'hello world',
+        'RAILPACK_JSON' => '{"token":"abc"}',
+        'RAILPACK_INSTALL_CMD' => 'npm ci && npm run postinstall',
+        'RAILPACK_DEPLOY_APT_PACKAGES' => 'curl wget',
+    ]);
+    expect($envArgs)->toContain("--env 'RAILPACK_NODE_VERSION=22'");
+    expect($envArgs)->toContain("--env 'RAILPACK_CUSTOM_FLAG=hello world'");
+    expect($envArgs)->toContain("--env 'RAILPACK_JSON={\"token\":\"abc\"}'");
+    expect($envArgs)->toContain("--env 'RAILPACK_INSTALL_CMD=npm ci && npm run postinstall'");
+    expect($envArgs)->toContain("--env 'RAILPACK_DEPLOY_APT_PACKAGES=curl wget'");
+    expect($envArgs)->not->toContain('RAILPACK_NULL');
+});
+
+it('uses preview railpack environment variables for preview deployments', function () {
+    $application = Mockery::mock(Application::class);
+    $application->shouldReceive('getAttribute')->with('install_command')->andReturn(null);
+
+    $previewValue = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $previewValue->forceFill([
+        'key' => 'RAILPACK_PREVIEW_ONLY',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $previewValue->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn('preview-value');
+
+    $previewQuery = Mockery::mock();
+    $previewQuery->shouldReceive('withoutBuildpackControlVariables')->once()->andReturnSelf();
+    $previewQuery->shouldReceive('where')->with('is_buildtime', true)->once()->andReturnSelf();
+    $previewQuery->shouldReceive('get')->once()->andReturn(collect([]));
+    $application->shouldReceive('environment_variables_preview')->once()->andReturn($previewQuery);
+
+    $railpackPreviewQuery = Mockery::mock();
+    $railpackPreviewQuery->shouldReceive('get')->once()->andReturn(collect([$previewValue]));
+    $application->shouldReceive('railpack_environment_variables_preview')->once()->andReturn($railpackPreviewQuery);
+
+    $job = Mockery::mock(ApplicationDeploymentJob::class)->makePartial();
+    $job->shouldAllowMockingProtectedMethods();
+    $job->shouldReceive('generate_coolify_env_variables')->andReturn(collect([]));
+
+    $reflection = new ReflectionClass(ApplicationDeploymentJob::class);
+    $applicationProperty = $reflection->getProperty('application');
+    $applicationProperty->setAccessible(true);
+    $applicationProperty->setValue($job, $application);
+
+    $pullRequestProperty = $reflection->getProperty('pull_request_id');
+    $pullRequestProperty->setAccessible(true);
+    $pullRequestProperty->setValue($job, 42);
+
+    $mainServerProperty = $reflection->getProperty('mainServer');
+    $mainServerProperty->setAccessible(true);
+    $mainServerProperty->setValue($job, Mockery::mock(Server::class));
+
+    $method = $reflection->getMethod('generate_railpack_env_variables');
+    $method->setAccessible(true);
+    $variables = $method->invoke($job);
+
+    expect($variables->all())->toBe([
+        'RAILPACK_PREVIEW_ONLY' => 'preview-value',
+        'RAILPACK_DEPLOY_APT_PACKAGES' => 'curl wget',
+    ]);
+});
+
+it('merges coolify env variables into railpack build variables', function () {
+    $application = Mockery::mock(Application::class);
+    $application->shouldReceive('getAttribute')->with('install_command')->andReturn(null);
+
+    $userVar = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $userVar->forceFill([
+        'key' => 'MY_BUILD_VAR',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $userVar->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn('hello');
+
+    $envQuery = Mockery::mock();
+    $envQuery->shouldReceive('withoutBuildpackControlVariables')->once()->andReturnSelf();
+    $envQuery->shouldReceive('where')->with('is_buildtime', true)->once()->andReturnSelf();
+    $envQuery->shouldReceive('get')->once()->andReturn(collect([$userVar]));
+    $application->shouldReceive('environment_variables')->once()->andReturn($envQuery);
+
+    $railpackQuery = Mockery::mock();
+    $railpackQuery->shouldReceive('get')->once()->andReturn(collect([]));
+    $application->shouldReceive('railpack_environment_variables')->once()->andReturn($railpackQuery);
+
+    $job = Mockery::mock(ApplicationDeploymentJob::class)->makePartial();
+    $job->shouldAllowMockingProtectedMethods();
+    $job->shouldReceive('generate_coolify_env_variables')
+        ->with(true)
+        ->andReturn(collect([
+            'COOLIFY_URL' => 'https://app.example.com',
+            'COOLIFY_FQDN' => 'app.example.com',
+            'COOLIFY_BRANCH' => 'main',
+            'COOLIFY_RESOURCE_UUID' => 'app-uuid',
+            'SOURCE_COMMIT' => 'abc123',
+            'EMPTY_VAR' => '',
+            'NULL_VAR' => null,
+        ]));
+
+    $reflection = new ReflectionClass(ApplicationDeploymentJob::class);
+    $applicationProperty = $reflection->getProperty('application');
+    $applicationProperty->setAccessible(true);
+    $applicationProperty->setValue($job, $application);
+
+    $pullRequestProperty = $reflection->getProperty('pull_request_id');
+    $pullRequestProperty->setAccessible(true);
+    $pullRequestProperty->setValue($job, 0);
+
+    $mainServerProperty = $reflection->getProperty('mainServer');
+    $mainServerProperty->setAccessible(true);
+    $mainServerProperty->setValue($job, Mockery::mock(Server::class));
+
+    $method = $reflection->getMethod('generate_railpack_env_variables');
+    $method->setAccessible(true);
+    $variables = $method->invoke($job);
+
+    expect($variables->all())->toBe([
+        'MY_BUILD_VAR' => 'hello',
+        'RAILPACK_DEPLOY_APT_PACKAGES' => 'curl wget',
+        'COOLIFY_URL' => 'https://app.example.com',
+        'COOLIFY_FQDN' => 'app.example.com',
+        'COOLIFY_BRANCH' => 'main',
+        'COOLIFY_RESOURCE_UUID' => 'app-uuid',
+        'SOURCE_COMMIT' => 'abc123',
+    ]);
+
+    $envArgsProperty = $reflection->getProperty('env_railpack_args');
+    $envArgsProperty->setAccessible(true);
+    $envArgs = $envArgsProperty->getValue($job);
+
+    expect($envArgs)->toContain("--env 'COOLIFY_URL=https://app.example.com'");
+    expect($envArgs)->toContain("--env 'SOURCE_COMMIT=abc123'");
+    expect($envArgs)->toContain("--env 'RAILPACK_DEPLOY_APT_PACKAGES=curl wget'");
+    expect($envArgs)->not->toContain('EMPTY_VAR');
+    expect($envArgs)->not->toContain('NULL_VAR');
+});
+
+it('preserves user railpack deploy apt packages while adding healthcheck tools once', function () {
+    $application = Mockery::mock(Application::class);
+    $application->shouldReceive('getAttribute')->with('install_command')->andReturn(null);
+
+    $deployPackages = Mockery::mock(EnvironmentVariable::class)->makePartial();
+    $deployPackages->forceFill([
+        'key' => 'RAILPACK_DEPLOY_APT_PACKAGES',
+        'is_literal' => false,
+        'is_multiline' => false,
+    ]);
+    $deployPackages->shouldReceive('getResolvedValueWithServer')->once()->with(Mockery::type(Server::class))->andReturn('ffmpeg curl');
+
+    $envQuery = Mockery::mock();
+    $envQuery->shouldReceive('withoutBuildpackControlVariables')->once()->andReturnSelf();
+    $envQuery->shouldReceive('where')->with('is_buildtime', true)->once()->andReturnSelf();
+    $envQuery->shouldReceive('get')->once()->andReturn(collect([]));
+    $application->shouldReceive('environment_variables')->once()->andReturn($envQuery);
+
+    $railpackQuery = Mockery::mock();
+    $railpackQuery->shouldReceive('get')->once()->andReturn(collect([$deployPackages]));
+    $application->shouldReceive('railpack_environment_variables')->once()->andReturn($railpackQuery);
+
+    $job = Mockery::mock(ApplicationDeploymentJob::class)->makePartial();
+    $job->shouldAllowMockingProtectedMethods();
+    $job->shouldReceive('generate_coolify_env_variables')->andReturn(collect([]));
+
+    $reflection = new ReflectionClass(ApplicationDeploymentJob::class);
+    $applicationProperty = $reflection->getProperty('application');
+    $applicationProperty->setAccessible(true);
+    $applicationProperty->setValue($job, $application);
+
+    $pullRequestProperty = $reflection->getProperty('pull_request_id');
+    $pullRequestProperty->setAccessible(true);
+    $pullRequestProperty->setValue($job, 0);
+
+    $mainServerProperty = $reflection->getProperty('mainServer');
+    $mainServerProperty->setAccessible(true);
+    $mainServerProperty->setValue($job, Mockery::mock(Server::class));
+
+    $method = $reflection->getMethod('generate_railpack_env_variables');
+    $method->setAccessible(true);
+    $variables = $method->invoke($job);
+
+    expect($variables->get('RAILPACK_DEPLOY_APT_PACKAGES'))->toBe('ffmpeg curl wget');
+
+    $envArgsProperty = $reflection->getProperty('env_railpack_args');
+    $envArgsProperty->setAccessible(true);
+    $envArgs = $envArgsProperty->getValue($job);
+
+    expect($envArgs)->toContain("--env 'RAILPACK_DEPLOY_APT_PACKAGES=ffmpeg curl wget'");
+});

tests/Unit/EnvironmentVariableBuildpackControlTest.php

@@ -0,0 +1,74 @@
+<?php
+
+use App\Models\EnvironmentVariable;
+use App\Models\SharedEnvironmentVariable;
+
+it('flags NIXPACKS_ keys as buildpack control variables', function () {
+    $env = new EnvironmentVariable;
+    $env->key = 'NIXPACKS_NODE_VERSION';
+
+    expect($env->is_buildpack_control)->toBeTrue();
+});
+
+it('flags RAILPACK_ keys as buildpack control variables', function () {
+    $env = new EnvironmentVariable;
+    $env->key = 'RAILPACK_NODE_VERSION';
+
+    expect($env->is_buildpack_control)->toBeTrue();
+});
+
+it('does not flag user-defined keys as buildpack control variables', function () {
+    $env = new EnvironmentVariable;
+    $env->key = 'MY_BUILD_VAR';
+
+    expect($env->is_buildpack_control)->toBeFalse();
+});
+
+it('does not flag empty key as buildpack control variable', function () {
+    $env = new EnvironmentVariable;
+
+    expect($env->is_buildpack_control)->toBeFalse();
+});
+
+it('lists is_buildpack_control in appends and drops legacy is_nixpacks', function () {
+    $env = new EnvironmentVariable;
+
+    expect($env->getAppends())->toContain('is_buildpack_control');
+    expect($env->getAppends())->not->toContain('is_nixpacks');
+});
+
+it('normalizes environment variable keys before storing them on the model', function () {
+    $env = new EnvironmentVariable;
+    $env->key = ' node.name ';
+
+    expect($env->key)->toBe('node.name');
+});
+
+it('allows Docker-compatible environment variable keys on the model', function (string $key) {
+    $env = new EnvironmentVariable;
+    $env->key = $key;
+
+    expect($env->key)->toBe($key);
+})->with([
+    'starts with digit' => '1BAD',
+    'hyphen' => 'BAD-KEY',
+    'dot' => 'node.name',
+    'uppercase dots' => 'XPACK.SECURITY.ENABLED',
+    'semicolon' => 'BAD;KEY',
+]);
+
+it('rejects environment variable keys Docker cannot represent on the model', function () {
+    $env = new EnvironmentVariable;
+
+    expect(function () use ($env) {
+        $env->key = 'BAD=KEY';
+    })->toThrow(InvalidArgumentException::class, 'Docker-compatible');
+});
+
+it('rejects shared environment variable keys Docker cannot represent on the model', function () {
+    $env = new SharedEnvironmentVariable;
+
+    expect(function () use ($env) {
+        $env->key = 'BAD=KEY';
+    })->toThrow(InvalidArgumentException::class, 'Docker-compatible');
+});

tests/Unit/ValidationPatternsTest.php

@@ -1,5 +1,6 @@
 <?php
 
+use App\Models\EnvironmentVariable;
 use App\Support\ValidationPatterns;
 
 it('accepts valid names with common characters', function (string $name) {
@@ -130,3 +131,45 @@ it('generates nullable dockerNetworkRules when not required', function () {
     expect($rules)->toContain('nullable')
         ->not->toContain('required');
 });
+
+it('accepts Docker-compatible environment variable keys', function (string $key) {
+    expect(ValidationPatterns::isValidEnvironmentVariableKey($key))->toBeTrue();
+})->with([
+    'letters' => 'APP_ENV',
+    'leading underscore' => '_TOKEN',
+    'railpack control variable' => 'RAILPACK_NODE_VERSION',
+    'digits after first character' => 'NODE_VERSION_20',
+    'starts with digit' => '1BAD',
+    'hyphen' => 'BAD-KEY',
+    'dot' => 'node.name',
+    'uppercase dots' => 'XPACK.SECURITY.ENABLED',
+    'semicolon' => 'BAD;KEY',
+    'space' => 'BAD KEY',
+]);
+
+it('rejects environment variable keys Docker cannot represent', function (string $key) {
+    expect(ValidationPatterns::isValidEnvironmentVariableKey($key))->toBeFalse();
+})->with([
+    'equals' => 'BAD=KEY',
+    'empty' => '',
+]);
+
+it('generates environment variable key rules with correct defaults', function () {
+    $rules = ValidationPatterns::environmentVariableKeyRules();
+
+    expect($rules)->toContain('required')
+        ->toContain('string')
+        ->toContain('max:255')
+        ->toContain('regex:'.ValidationPatterns::ENVIRONMENT_VARIABLE_KEY_PATTERN);
+});
+
+it('normalizes environment variable keys by trimming surrounding whitespace', function () {
+    expect(ValidationPatterns::normalizeEnvironmentVariableKey(' node.name '))->toBe('node.name');
+});
+
+it('normalizes environment variable keys before model validation', function () {
+    $environmentVariable = new EnvironmentVariable;
+    $environmentVariable->key = ' APP_ENV ';
+
+    expect($environmentVariable->key)->toBe('APP_ENV');
+});