Skip to content

Org Manifests

Jump to bottom
Jannis Schreiber edited this page Dec 29, 2024 · 19 revisions

A org manifest is a complete definition of all packages and unpackaged metadata that should be "installed" on the target org. The manifest describes the desired state, not the things that change with this release.

Commands in this hierarchy let you generate, validate and rollout release manifests. The rollout command automatically determines if an artifact needs to be installed or can be skipped.

Key Concepts Of The Org Manifest

At the top level, an org manifest consists of enviroments, artifacts, and options. The heart of a manifest is the list of artifacts, that will be rolled out in the configured order. Each artifact mutates the Org. See Artifacts to learn more about supported types and how they are rolled out.

By convention, naming artifacts or environments follows snake_case. The entire manifest is rolled out through all environments (e.g. Dev, UAT, Prod). A rollout is complete, if all environments in your Org Hierarchy are in sync.

environments:
  dev: admin@example.com.dev
  qa: admin@example.com.qa
  prod: admin@example.com
artifacts:
  org_settings:
    type: Unpackaged
    path: src/unpackaged/org-settings
  apex_utils:
    type: UnlockedPackage
    package_id: 0Ho...
    version: 1.30.3
    skip_if_installed: false
  lwc_utils:
    type: UnlockedPackage
    package_id: 0Ho...
    version: 1.0.0
  core_crm:
    type: UnlockedPackage
    package_id: 0Ho...
    version: 3.1.2
  pims:
    type: UnlockedPackage
    version: 2.1.1
    package_id: ...
  pims_overrides:
    type: Unpackaged
    path: src/unpackaged/package-overrides/pims

Environments

Environments are optional, you only need to define them, if you want to deploy different source based on the target environment. They are the fundamental link between your Org Hierarchy, your pipeline implementation, and the release manifest.

The engine evaluates the username of the target org it is currently deploying to. If it finds a match in the environments object, this match is used in SourceDeploy tasks (Unpackaged artifacts) to determine the source path. Read more here: Source Path.

Artifacts

This object is an ordered list of artifacts to deploy or install on the target org. Each artifact is evaluated individually. Each entry consists of an arbitrary name of the artifact (e.g. utils, sales, order_management, etc) and its definition.

Unlocked Packages

Unlocked packages are the most obvious artifacts. They make use of a DevHub's native artifact registry. They are currently only supported, if the specified DevHub (at pipeline level) owns all packages. You must specify the package id and the desired version to install, so the engine can resolve it to the correct subscriber package version id.

Unlocked packages are installed with the basic "sf package install" command and allow some additional options.

skip_if_installed (Optional, Default: true): If the desired package version is already installed on the target, this package is skipped. When a package is skipped, its overrides are skipped as well.

package_id (Required): ...

version (Required): ...

installation_key (Optional): ...

Handling Installation Keys

Installation keys are treated as secrets. You can't set them via command parameters or hard-code them in the manifest file. Instead, they are set as environment variables. Your plan file defines the variable name that is read for the installation key. If a package does not define an installation key variable name in the manifest, the engine tries to install it without a key.

pims:
  package_id: 0Ho0X0000000000AAA
  installation_key: PIMS_INSTALLATION_KEY
core_crm:
  package_id: 0Ho0X0000000001AAA
  installation_key: CORE_INSTALLATION_KEY

If you want to run the command locally, you can store installation keys in a file and set the key-file as a parameter for the rollout command. For example, create a file keys.env in a folder secrets in your project with your installation keys.

# your actual installation keys - don't commit this!
PIMS_INSTALLATION_KEY=TJHfwVFUGw...
CORE_INSTALLATION_KEY=xiEdLdUQGoQ...
etc

Now, you can use this file when running the rollout command.

sf jsc manifest rollout --manifest my-org-manifest.yaml --installation-keys secrets/keys.env

Managed Packages

Similar to unlocked packages, you can also specify managed packages. However, no DevHub is required.

Unpackaged

Any unpackaged metadata (in source format) can be specified as an "Unpackaged" artifact. A release manifest fundamentally does not distinguish between basic org settings, a package override or an unpackaged app. Its up to you how you organize the source files and configure your manifest to roll them out.

skip_if_unchanged (Optional, Default: true): Similar to an unlocked package, you can tell the engine to skip

Source Path

Each unpackaged artifact has two options: a single source path or a mapping of source paths per environment. A single path always deploys the same source, regardless of the target environment:

pims_overrides:
  type: Unpackaged
  path: src/package-overrides/pims/main

Individual paths for each environment can be specified for every env in the environments object. If you define individual paths, the engine only deploys mapped environments. In other words: If you define prod in your environments object, but do not specify a path for prod in package overrides, no post install source will be deployed, if the package is installed on prod.

pims_overrides:
  type: Unpackaged
  path:
    dev: src/package-overrides/pims/dev
    qa: src/package-overrides/pims/dev
    prod: src/package-overrides/pims/main

Cron Jobs

Not implemented yet

Garbage Disposal

Not implemented yet

Options

The behaviour of the engine can be configured to certain aspects. If a setting can be set on manifest level and artifact level, the artifact always takes precedence, if present.

Currently, settings are not implemented. Default behaviour is executed.

skip_if_installed (Default: true): For all package artifacts, skip installation if the resolved version is already installed

requires_promoted_versions (Default: true): Validate, that the package version is promoted and fail, if it isn't. Ignores if the target org is a Sandbox or Production.

strict_environments (Default: true): If false, ignores, if the target org is not present in mapped environments. If no match is found for a path-mapping, the step is skipped. If true, an error is raised.

pipefail (Default: true): If true, an error in the artifacts pipe fails the entire rollout. If false, the rollout proceeds (but other errors may occur, due to dependencies).

Handling Multi-DevHub Environments

At the moment, the manifest command only supports a single DevHub. The DevHub is needed to resolve package versions (1.2.3) to the correct 04t... ids. If you have multiple DevHubs, you need to create one manifest.yaml per DevHub and call the sf jsc manifest rollout once per manifest.

Command Concepts

Manifest generate

Reserved for future use

Manifest validate

Reserved for future use

Manifest rollout

placeholder

Clone this wiki locally