Configure environment manifests

Environment manifests describe shared sandbox setup. Repository manifests describe setup for a particular checkout. Use them for the commands and supporting files a fresh environment needs before the agent begins its task.

Play explainer 12 sec

Create or edit a manifestCopy Anchor Link

Open Settings → Manifests. The page separates environment manifests from repository manifests. Use the action for the intended scope, or Add manifest under the relevant repository.

Enter the YAML, add any supporting files referenced by it, and save. Read validation errors before activating the revision. Confirm which revision is active after the action completes.

Start with a minimal exampleCopy Anchor Link

For a repository that has a committed lockfile and uses npm:

hydrate:
  - run: npm ci

This installs dependencies during repository hydration. It assumes npm is available and the checkout contains a valid lockfile. Use your project's package manager and deterministic install command.

The supported phases are initialize, hydrate, knowledge, and post-build. A phase contains a list of run steps or supporting-file copies:

hydrate:
  - file: setup-config.json
    dest: config/setup-config.json
  - run: npm ci

Add setup-config.json as a supporting file. File and destination paths must be safe relative paths. Do not paste credentials into YAML or supporting files; use secrets.

Activate and verifyCopy Anchor Link

Saving an edit and using a revision for new builds are separate concerns. Review the active revision and the resulting build or snapshot status. Inspect a failed step's command and error before retrying.

Configuration changes do not rewrite a machine that is already running an older environment. Use snapshots and rebuilds to understand what a new session will start from.

Keep manifests limited to reproducible setup. Put task-specific instructions in a prompt, rule, or skill.