Changelog

6.3.0 (unreleased)

Providers

  • Craft Application can now build on a provider using a different architecture from the host architecture as long as the provider supports that architecture. Set the CRAFT_BUILD_ON environment variable to an architecture to use this. When this is the case, in the provider instance the snap is installed from the store rather than being injected from the host.

Commands

  • The test command now reads spread.yaml before beginning the lifecycle, erroring early if the file is invalid.

For a complete list of commits, check out the 6.3.0 release on GitHub.

6.2.2 (2026-03-12)

Documentation

  • Fix a misspelling.

For a complete list of commits, check out the 6.2.2 release on GitHub.

6.2.1 (2026-03-06)

Bug fixes

  • The Application now sets the plugin group on application load.

Documentation

For a complete list of commits, check out the 6.2.1 release on GitHub.

6.2.0 (2026-02-12)

Services

  • The Provider service now injects the application’s base snap from the host into the build environment.

Bug Fixes

  • Files for the test command, spread.yaml and spread/, no longer cause the part’s build directory to be marked as dirty by Git.

For a complete list of commits, check out the 6.2.0 release on GitHub.

6.1.1 (2026-01-27)

Bug fixes

  • The project service’s base_eol_soon_date() method no longer raises an exception on unknown bases.

For a complete list of commits, check out the 6.1.1 release on GitHub.

6.1.0 (2026-01-20)

Services

Application

  • If a lifecycle command is run with --destructive-mode, but without root, a warning will be emitted about potentially unexpected behavior.

  • Direct registration of plugins in the Application is deprecated, as it’s mutually incompatible with the registration of plugin groups.

Pytest plugin

  • The pytest plugin now includes an auto-used reset_craft_environment() fixture to prevent relevant externally-set environment variables from causing test failures.

For a complete list of commits, check out the 6.1.0 release on GitHub.

6.0.1 (2025-11-19)

Models

  • The list of invalid platform names for the JSON schema is now sorted.

For a complete list of commits, check out the 6.0.1 release on GitHub.

6.0.0 (2025-11-17)

Models

  • Pydantic error messages now include the input value when relevant.

Breaking changes

Dependencies

  • The pygit2 dependency is more broadly defined. Applications may need to constrain this dependency further if they are packaged as snaps.

Models

  • The summary and description fields on the Project model are now mandatory, but are adoptable fields by default. Apps that override the project_variables or mandatory_adoptable_fields fields of AppMetadata must consider how these fields should behave in their apps.

  • any and * are now reserved names for platforms.

  • Platform names may not contain ‘/’ characters.

  • Ubuntu Questing is now a ‘stable’ base, and Resolute is added as the new ‘devel’ one.

  • Add a classmethod on the Project class to let applications fine-tune which bases are considered ‘devel’.

Fetch Service

  • When using the fetch service, the environment variable CRAFT_PROVIDERS_EXPERIMENTAL_SUPPRESS_UPGRADE_UNSUPPORTED gets set, suppressing running dist-upgrades on instance creation.

Utilities

  • format_pydantic_error now takes a pydantic ErrorDetails rather than a location and message.

  • format_pydantic_errors now takes ErrorDetails instead of ErrorDict objects. In most cases, apps will already be passing ErrorDetails objects.

For a complete list of commits, check out the 6.0.0 release on GitHub.

5.11.0 (2025-10-01)

Documentation

  • Add common page Reuse packages between builds for use in apps’ documentation.

For a complete list of commits, check out the 5.11.0 release on GitHub.

5.10.3 (2025-09-22)

Application

  • If keys are duplicated in a project file’s dictionaries after the grammar is resolved, an error will be raised.

For a complete list of commits, check out the 5.10.3 release on GitHub.

5.10.2 (2025-09-19)

  • Launchpad requests no longer ignore proxy settings.

For a complete list of commits, check out the 5.10.2 release on GitHub.

5.10.1 (2025-09-12)

  • The Application class no longer catches all BaseException instances, reverting back to the previous behaviour of catching Exception and KeyboardInterrupt exceptions.

For a complete list of commits, check out the 5.10.1 release on GitHub.

5.10.0 (2025-09-10)

Application

  • Add artifact_type to AppMetadata to allow user-visible messages to refer to the app-specific output artifact type.

  • Improved UX for end-of-life and near end-of-life bases with check_supported_base.

  • When packing with --debug, the offending error message will now be displayed twice - once just before entering the shell, and again after the shell is closed.

Configuration

  • Add an idle_time configuration option that sets the Provider service’s idle timer duration.

Models

  • Support debug and debug-each in all locations in the spread.yaml model.

  • Update the current development release for the Project model.

Services

  • Add an idle timer to the Provider service, so app instances can reuse a dormant VM or container before it automatically shuts down.

  • Bases that are in extended support are now correctly classified as EOL.

For a complete list of commits, check out the 5.10.0 release on GitHub.

5.9.1 (2025-09-04)

Services

  • The Lifecycle Service no longer improperly caches the project (fixes adopt-info).

For a complete list of commits, check out the 5.9.1 release on GitHub.

5.9.0 (2025-08-29)

Services

  • Previously, only top-level keys in a project file could be managed with craftctl. Now, nested keys in a project file can be managed.

  • Previously, all project variables could only be set by a single part. Now the handling is more granular — each project variable can be set by a different part.

  • Applications can override the Project service’s _create_project_vars() method to define which keys can be managed and which parts can set them.

For a complete list of commits, check out the 5.9.0 release on GitHub.

5.8.0 (2025-08-28)

Application

  • Add the for selector to the YAML grammar. With it, crafters can set different values depending on the active platform.

Services

  • Project Service: Allow using base: bare with check_supported_base.

For a complete list of commits, check out the 5.8.0 release on GitHub.

5.7.1 (2025-08-27)

Services

  • Prevent the reuse of instances created before the State service was added by updating the Provider service’s compatibility tag.

Pytest plugin

For a complete list of commits, check out the 5.7.1 release on GitHub.

5.6.5 (2025-08-20)

Services

  • Prevent the reuse of instances created before the State service by updating the Provider service’s compatibility tag.

For a complete list of commits, check out the 5.6.5 release on GitHub.

5.7.0 (2025-08-15)

Application

  • Add a check_supported_base option to AppMetadata, allowing the application to opt into checking that the base is supported.

Services

  • Add a new Proxy service that configures an instance to connect to a proxy.

  • The Provider Service can now add early proxy configuration to instances.

  • The Lifecycle service now configures the overlay to use old-releases.ubuntu.com if the release has been migrated to that domain.

For a complete list of commits, check out the 5.7.0 release on GitHub.

5.6.4 (2025-08-15)

Fixes

  • The --project-dir command option works again.

For a complete list of commits, check out the 5.6.4 release on GitHub.

5.6.3 (2025-08-05)

Fixes

  • Check the craft backend type before testing. The type must be craft to allow the backend to be dynamically processed.

For a complete list of commits, check out the 5.6.3 release on GitHub.

5.6.2 (2025-08-01)

Services

  • Fix a bug where the State service had insufficient permissions to write to the state directory.

For a complete list of commits, check out the 5.6.2 release on GitHub.

5.6.1 (2025-07-28)

Application

  • Applications must opt into skipping repack. This was done because it’s not fully backwards compatible (see: #821)

For a complete list of commits, check out the 5.6.1 release on GitHub.

5.6.0 (2025-07-24)

Application

  • Allow applications to override the execution of lifecycle actions.

For a complete list of commits, check out the 5.6.0 release on GitHub.

5.5.0 (2025-07-17)

Services

  • Add a new State service that manages a global state between manager and managed instances of an application.

  • Make the Project service compatible with multi-base platform definitions.

Commands

  • The pack command will only repack if necessary. The test command will not recreate packages that already exist if the project has not been modified.

  • The test command will test all packed platforms.

For a complete list of commits, check out the 5.5.0 release on GitHub.

5.4.0 (2025-06-30)

Models

  • Expose the Part type.

Commands

  • The test command now accepts Spread test expressions.

For a complete list of commits, check out the 5.4.0 release on GitHub.

5.3.0 (2025-05-28)

Application

  • _set_global_environment method marked as deprecated for removal in the next major release.

Commands

  • Reduce spread verbosity level when running the test command.

Git

  • Add API to modify repository configuration.

Services

  • Add a get_all() method to the ConfigService, which returns a dict of all current configuration values.

  • The ProviderService now passes all values from the ConfigService to the inner instance’s environment.

Fixes

  • Fix an issue where the fetch-service would fail to find the network used by LXD containers.

  • Improve test result messages.

  • InitService no longer leaves empty files if rendering template fails.

  • Enable terminal output when testing with --debug, --shell, or --shell-after parameters.

  • Don’t repull sources on test files changes.

  • Generate artifacts for testing in the project root directory.

  • Normalize the list of artifacts packed in PackageService to be relative to the project root directory.

For a complete list of commits, check out the 5.3.0 release on GitHub.

5.2.1 (2025-05-23)

Services

  • CRAFT_PARALLEL_BUILD_COUNT and CRAFT_MAX_PARALLEL_BUILD_COUNT are now forwarded to managed instances.

For a complete list of commits, check out the 5.2.1 release on GitHub.

5.2.0 (2025-04-25)

Commands

  • The test command now accepts paths to specific tests as well as the --debug, --shell and --shell-after parameters.

Models

  • A new how-to guide describes how to implement application-specific platforms keys.

Services

  • The TestingService now sets environment variables containing the names of the generated artifact and resource files.

For a complete list of commits, check out the 5.2.0 release on GitHub.

5.1.0 (2025-04-24)

Application

  • The application now has craft-cli capture logs from HTTPX by default, logging store requests for craft-store’s Publisher Gateway.

Fixes

  • #698 - the spread backend model now allows string system names (not just mappings).

  • Set a system matching the host when running the test command on CI.

For a complete list of commits, check out the 5.1.0 release on GitHub.

5.0.4 (2025-04-24)

Fixes

  • Fix inconsistent command output in GitRepo.remote_contains by removing colors and columns.

For a complete list of commits, check out the 5.0.4 release on GitHub.

5.0.3 (2025-04-14)

Fixes

  • #716 - prime command fails in managed mode

  • Correctly set SSL_CERT_DIR during pygit2 import on non-Ubuntu systems.

For a complete list of commits, check out the 5.0.3 release on GitHub.

5.0.2 (2025-04-11)

Fixes

  • The craft-spread base model now contains an optional project key. It is currently overwritten by the test command.

For a complete list of commits, check out the 5.0.2 release on GitHub.

5.0.1 (2025-04-10)

Commands

  • test raises a clear error message if spread.yaml or the spread executable is missing.

  • The warning that the test command is experimental is only displayed once.

  • test no longer overwrites spread.yaml

Services

  • The TestingService now outputs a correct discard script for spread.

  • Platforms models are more strictly validated.

  • Raise ProjectGenerationError instead of RuntimeError in ProjectService when a project fails to generate.

  • spread.yaml files are parsed strictly for top level keys, but pass through second level keys to the spread process.

  • Spread tests run on their runners as root.

Fixes

  • Logs generated by the inner instance of the provider service no longer include doubled timestamps.

  • Errors implementing the CraftError protocol are properly caught and presented.

For a complete list of commits, check out the 5.0.1 release on GitHub.

5.0.0 (2025-03-26)

Services

  • A new ProjectService now handles project loading and rendering. Services and commands can use this to get a project. The abstract ProjectService is no longer available for inheritance.

  • Setting the arguments for a service using the service factory’s set_kwargs is deprecated. Use update_kwargs instead.

Testing with pytest

  • Add a pytest plugin with a fixture that enables production mode for the application if a test requires it.

Breaking changes

  • The pytest plugin includes an auto-used fixture that puts the app into debug mode by default for tests.

  • Support for secrets has been removed.

  • The abstract class ProjectService has been removed. Services can no longer designate that they require a project, but should instead use the get() method of the ProjectService to retrieve the project. It will error accordingly.

  • The BuildPlanner pydantic model has been replaced with the BuildPlanService

  • The internal BuildInfo model is replaced with craft_platforms.BuildInfo

For a complete list of commits, check out the 5.0.0 release on GitHub.

4.10.0 (2025-02-27)

Application

  • Add an API for additional snaps to be installed in the managed instance by the provider service.

  • Increase timeout in fetch-service queries.

For a complete list of commits, check out the 4.10.0 release on GitHub.

4.9.1 (2025-02-12)

Application

  • Load python plugins after the emitter has been initialized so they can be logged.

For a complete list of commits, check out the 4.9.1 release on GitHub.

4.9.0 (2025-02-10)

All bug fixes from the 4.8 and 4.4 series are included in 4.9.0.

Application

  • Add a feature to allow Python plugins to extend or modify the behaviour of applications that use craft-application as a framework. The plugin packages must be installed in the same virtual environment as the application.

Remote build

  • Add hooks to further customize functionality

  • Add a --project parameter for user-defined Launchpad projects, including private projects.

  • Add “pending” as a displayed status for in-progress remote builds

For a complete list of commits, check out the 4.9.0 release on GitHub.

4.4.1 (2025-02-05)

Application

  • Fix an issue with processing fetch-service output.

  • The fetch-service integration now assumes that the fetch-service snap is tracking the latest/candidate channel.

Remote build

  • Fix a bug where repositories and recipes for private Launchpad projects would be public while the build was in progress.

For a complete list of commits, check out the 4.4.1 release on GitHub.

4.8.3 (2025-01-31)

Remote build

  • Fix a bug where repositories and recipes for private Launchpad projects would be public while the build was in progress.

  • Fix a bug where the remote-build command would suggest running an invalid command.

  • Fix a bug where a timeout would cause the remote builder to remove an ongoing build.

For a complete list of commits, check out the 4.8.3 release on GitHub.

4.8.2 (2025-01-16)

Application

  • Fix an issue with processing fetch-service output.

For a complete list of commits, check out the 4.8.2 release on GitHub.

4.8.1 (2025-01-13)

Application

  • Do not log encoded secrets in managed mode if build_secrets AppFeature is enabled.

Documentation

  • Add missing links to the GitHub releases.

For a complete list of commits, check out the 4.8.1 release on GitHub.

4.8.0 (2025-01-13)

Services

  • Fix a bug where the same build environment was reused for platforms with the same build-on and build-for architectures.

Utils

  • Add format_timestamp() helper that helps with formatting time in command responses.

  • Add is_managed_mode() helper to check if running in managed mode.

  • Add get_hostname() helper to get a name of current host.

For a complete list of commits, check out the 4.8.0 release on GitHub.

4.7.0 (2024-12-19)

Application

  • Allow applications to implement multi-base build plans.

For a complete list of commits, check out the 4.7.0 release on GitHub.

4.6.0 (2024-12-13)

Application

  • Add support for keeping order in help for commands provided to add_command_group().

  • Add support for rock launchpad recipes, allowing the remote build of rocks.

Commands

  • Add a remote-build command. This command is not registered by default, but is available for application use.

Git

  • Extend the craft_application.git module with the following APIs:

    • Add is_commit(ref) and is_short_commit(ref) helpers for checking if a given ref is a valid commit hash.

    • Add a Commit model to represent the result of get_last_commit().

  • Extend the GitRepo class with additional methods:

    • Add set_remote_url() and set_remote_push_url() methods and their getter counterparts.

    • Add set_no_push() method, which explicitly disables push for specific remotes.

    • Add get_last_commit() method, which retrieves the last commit hash and message.

    • Add get_last_commit_on_branch_or_tag() method, which retrieves the last commit associated with a given ref.

    • Add fetch() method, which retrieves remote objects.

  • Use craft.git for Git-related operations run with subprocess in GitRepo.

For a complete list of commits, check out the 4.6.0 release on GitHub.

4.5.0 (2024-11-28)

Application

  • The fetch-service integration now assumes that the fetch-service snap is tracking the latest/candidate.

  • Fix an issue where the fetch-service output was not correctly logged when running in a snapped craft tool.

Commands

  • Provide a documentation link in help messages.

  • Updates to the init command:

    • If the --name argument is provided, the command now checks if the value is a valid project name, and returns an error if it isn’t.

    • If the --name argument is not provided, the command now checks whether the project directory is a valid project name. If it isn’t, the command sets the project name to my-project.

Services

  • Add version to the template generation context of InitService.

For a complete list of commits, check out the 4.5.0 release on GitHub.

4.4.0 (2024-11-08)

Application

  • AppCommand subclasses now will always receive a valid app_config dict.

  • Fixes a bug where the fetch-service integration would try to spawn the fetch-service process when running in managed mode.

  • Cleans up the output from the fetch-service integration.

Commands

  • Adds an init command for initializing new projects.

  • Lifecycle commands are ordered in the sequence they run rather than alphabetically in help messages.

  • Preserves order of CommandGroups defined by the application.

  • Applications can override commands defined by Craft Application in the same CommandGroup.

Services

  • Adds an InitService for initializing new projects.

For a complete list of commits, check out the 4.4.0 release on GitHub.

4.3.0 (2024-10-11)

Application

  • Added compatibility methods for craft-platforms models.

Commands

  • The clean command now supports the --platform argument to filter which build environments to clean.

Services

  • Added an experimental integration with the fetch-service, to generate manifests listing assets that were downloaded during the build.

For a complete list of commits, check out the 4.3.0 release on GitHub.

4.2.7 (2024-10-08)

  • Don’t depend on requests >= 2.32.0.

  • Fix: set CRAFT_PARALLEL_BUILD_COUNT correctly in override- scripts.

For a complete list of commits, check out the 4.2.7 release on GitHub.

4.2.6 (2024-10-04)

  • Remove the requests<2.32.0 constraint to resolve CVE-2024-35195.

For a complete list of commits, check out the 4.2.6 release on GitHub.

4.2.5 (2024-10-04)

Services

  • The config service handles snap issues better.

For a complete list of commits, check out the 4.2.5 release on GitHub.

4.2.4 (2024-09-19)

Remote build

  • Remote build errors are now a subclass of CraftError.

For a complete list of commits, check out the 4.2.4 release on GitHub.

4.2.3 (2024-09-18)

Application

  • get_arg_or_config now correctly checks the config service if the passed namespace has None as the value of the requested item.

For a complete list of commits, check out the 4.2.3 release on GitHub.

4.2.2 (2024-09-13)

Application

  • Add a _run_inner method to override or wrap the core run logic.

For a complete list of commits, check out the 4.2.2 release on GitHub.

4.2.1 (2024-09-13)

Models

  • Fix a regression where numeric part properties could not be parsed.

For a complete list of commits, check out the 4.2.1 release on GitHub.

4.1.3 (2024-09-12)

Models

  • Fix a regression where numeric part properties could not be parsed.

For a complete list of commits, check out the 4.1.3 release on GitHub.

4.2.0 (2024-09-12)

Application

  • Add a configuration service to unify handling of command line arguments, environment variables, snap configurations, and so on.

  • Use the standard library to retrieve the host’s proxies.

Commands

  • Properly support --shell, --shell-after and --debug on the pack command.

For a complete list of commits, check out the 4.2.0 release on GitHub.

4.1.2 (2024-09-05)

Application

  • Managed runs now fail if the build plan is empty.

  • Error message tweaks for invalid YAML files.

Models

  • Platform models now correctly accept non-vectorised architectures.

For a complete list of commits, check out the 4.1.2 release on GitHub.

4.1.1 (2024-08-27)

Application

  • When a build fails due to matching multiple platforms, those matching platforms will be specified in the error message.

  • Show nicer error messages for invalid YAML files.

For a complete list of commits, check out the 4.1.1 release on GitHub.

4.1.0 (2024-08-14)

Application

If an app isn’t running from snap, the installed app will install the snap in the provider using the channel in the CRAFT_SNAP_CHANNEL environment variable, defaulting to latest/stable if none is set.

Services

The LifecycleService now breaks out a _get_build_for method for apps to override if necessary.

For a complete list of commits, check out the 4.1.0 release on GitHub.

4.0.0 (2024-08-09)

Breaking changes

This release migrates to pydantic 2. Most exit codes use constants from the os module. (This makes craft-application 4 only compatible with Windows when using Python 3.11+.)

Models

Add constrained string fields that check for SPDX license strings or the license string “proprietary”.

CraftBaseModel now includes a to_yaml_string method.

Custom regex-based validators can be built with models.get_validator_by_regex. These can be used to make a better error message than the pydantic default.

Git

The git submodule under launchpad is now its own module and can clone repositories and add remotes.

For a complete list of commits, check out the 4.0.0 release on GitHub.

3.2.0 (2024-07-07)

Application

Add support for versioned documentation urls - that is, urls that point to the documentation for the specific version of the running application.

Documentation

Add a how-to guide for using partitions.

For a complete list of commits, check out the 3.2.0 release on GitHub.

3.1.0 (2024-07-05)

Note

3.1.0 includes changes from the 2.9.0 release.

Remote build

Add a credentials_filepath property to the RemoteBuildService so that applications can point to a different Launchpad credentials file.

For a complete list of commits, check out the 3.1.0 release on GitHub.

2.9.0 (2024-07-03)

Application

  • Support doc slugs for craft-parts build errors, to point to the plugin docs.

  • Support setting the base docs url on the AppMetadata, used in conjunction with slugs to build full urls.

  • Add a method to enable craft-parts Features. This is called at a specific point so that things like command groups can rely on the features being set.

  • Ensure the craft-providers’ provider is available before launching.

Models

  • Fix and normalize project validation errors. Never raise CraftValidationErrors directly in validators.

  • Add a way to provide doc slugs for models. These are shown when a project fails validation, provided the base docs url is set on the AppMetadata.

3.0.0 (2024-06-28)

Craft Application 3.0.0 implements the BuildPlanner class and can create a build plan. This is a breaking change because it requires more fields to be defined.

Warning

platforms is now a required field in the Project

platforms, base, and build-base are now required fields in the BuildPlanner model

Application

  • Extends add_command_groups() to accept a sequence instead of a list.

  • Adds support for building architecture-independent artefacts by accepting all as the build-for target.

Models

  • Adds a default Platform model. See platforms for a reference of the model.

  • Adds a default get_build_plan() function to the BuildPlanner class. See Build plans for an explanation of how the default get_build_plan() works.

  • Changes BuildPlanner from an abstract class to a fully implemented class. Applications can now use the BuildPlanner class directly.

For a complete list of commits, check out the 3.0.0 release on GitHub.

2.8.0 (2024-06-03)

Commands

  • Fixes a bug where the pack command could accept a list of parts as command line arguments.

  • Adds support for commands to accept multiple platform or build-for values from the command line as comma-separated values.

Remote build

  • Retries more API calls to Launchpad.

  • Adds an exponential backoff to API retries with a maximum total delay of 62 seconds.

  • Fixes a bug where the full project name was not used in the remote build log files.

For a complete list of commits, check out the 2.8.0 release on GitHub.

2.7.0 (2024-05-08)

Base naming convention

Applications that use a non-default base naming convention must implement Project._providers_base() to translate application-specific base names into a Craft Providers base.

The default base naming convention is <distribution>@<series>. For example, ubuntu@24.04, centos@7, and almalinux@9.

LifecycleCommand

Adds a new LifecycleCommand class that can be inherited for creating application-specific lifecycle commands.

_needs_project()

Adds a new command function _needs_project() that can be overridden by subclasses. It’s similar to the always_load_project class variable but takes parsed_args as a parameter. The default value is always_load_project.

For a complete list of commits, check out the 2.7.0 release on GitHub.