Skip to content

Move environment option into build stanza and document it#2807

Open
bfirsh wants to merge 1 commit intomainfrom
move-environment-to-build
Open

Move environment option into build stanza and document it#2807
bfirsh wants to merge 1 commit intomainfrom
move-environment-to-build

Conversation

@bfirsh
Copy link
Member

@bfirsh bfirsh commented Mar 4, 2026

Summary

  • Moves the environment cog.yaml option from the top level into the build: stanza, since it's a build-time setting that adds env vars to the Docker image
  • Adds documentation for environment in docs/yaml.md
  • Maintains backward compatibility: top-level environment still works but emits a deprecation warning

Changes

Config structs: Environment and parsedEnvironment moved from Config to Build. The canonical location is now build.environment.

Backward compatibility: A new resolveEnvironment() validation step handles migration:

  • Top-level only → migrated into build.environment with a deprecation warning
  • build.environment only → no-op
  • Both set → validation error

JSON schema: environment added to build properties; top-level kept with deprecation note.

Documentation: New ### environment section under ## build in docs/yaml.md (alphabetically between cuda and gpu). Documents the NAME=value format, provides an example, and notes reserved variable names.

Tests: Integration test and YAML overwrite test fixtures updated to use the new location.

Example

# New (preferred)
build:
  python_version: "3.12"
  environment:
    - NAME=michael
    - TEST_VAR=test_value

# Old (still works, emits deprecation warning)
build:
  python_version: "3.12"
environment:
  - NAME=michael
  - TEST_VAR=test_value

The environment cog.yaml option is a build-time setting that adds
environment variables to the Docker image, so it belongs in the build
stanza rather than at the top level.

- Move Environment field from Config to Build struct
- Accept top-level environment with a deprecation warning for backward
  compatibility; error if set in both places
- Add environment to the JSON schema under build properties
- Add documentation to docs/yaml.md
- Update integration test and YAML overwrite test fixtures
- Regenerate docs/llms.txt
@bfirsh bfirsh requested a review from a team as a code owner March 4, 2026 23:17
@michaeldwan michaeldwan added this to the 0.18.0 milestone Mar 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants