Charmcraft Configuration

The charmcraft tool configuration is specified in a charmcraft.yaml file located in the project’s root directory.

By default, Charmcraft will try to find that file in the current directory, but in case of needing to run charmcraft outside the project’s directory, it can be specified using the global option --project-dir.

From Charmcraft v0.8.0 onwards, this configuration file mandatory for packing bundles, but is optional for the rest of the commands.

In a future release this will change, and the charmcraft.yaml file will become mandatory for all project-handling commands (will keep being optional for some store-related commands).

Configuration content

The following are the fields available in the configuration file. Everything is optional unless stated otherwise.

# (Required) The type of entity for which the present config exists
type: charm | bundle

# (Optional) Used for configuring charmcraft's interaction with store servers
charmhub:

    # (Optional) Base URL for the Charmhub API - default used if not set. 
    # Used mostly in the context of "private" charm stores.
    api-url: <api url>

    # (Optional) Base URL to push binaries to Charmhub - default used if not set.
    # Used mostly in the context of "private" charm stores.
    storage-url: <storage url>

# (Optional) List of files/directories to include in the built file. 
parts:

    # (Optional) Specify parts for a charm if `type`is set to `charm`.
    charm:

        # (Optional, new in charmcraft 1.2) The charm entry point, relative to the project
        # directory. If not defined, `src/charm.py` will be used.
        charm-entrypoint: /path/to/entrypoint

        # (Optional, new in charmcraft 1.2) Requirement files. If not defined, `requirements.txt`
        # will be used if it's present in the project directory.
        charm-requirements:
            - requirements-1.txt
            - requirements-2.txt

        # (Optional) List of files to include. Note that `bundle.yaml`, the entry point
        # file and hooks are included automatically when packing a charm. Additionaly,
        # `config.yaml`, `metrics.yaml`, `actions.yaml`, `lxd-profile.yaml`, `templates`,
        # `version`, `lib` and `mod` will be included if they exist in the project directory.
        prime:
            - /path/to/file1
            - /path/to/file2

    # (Optional) Specify parts for a bundle if `type` is set to `bundle`.
    bundle:

        # (Optional) List of files to include. Note that `metadata.yaml` is included
        # automatically when packing a bundle.
        prime:
            - /path/to/file1
            - /path/to/file2

# (Optional) Expected in Charmcraft 1.1+. A list of base configurations specifying
# environments charms must be built on, and run on.
#
# There are two forms of base definition, both are indicated below.
bases:
    
    # (Optional) Short form base definition. Implies that the specified base is 
    # to be used for both `build-on` and `run-on`.
    - name: <name>
      channel: <channel>
      # (Optional) List of architecture strings, defaults to machine architecture
      architectures:
          - <arch>

    # (Optional) Expanded, long-form definition
    - build-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

      run-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

# (Optional, new in charmcraft 1.2) Control the analysis behaviour when explicitly running the 
# `analyze` command or implicitly running `pack`
analysis:
    # (Optional) Any attribute/lint analysis listed here (by name) will be ignored 
    ignore:
        attributes: [<check>,...]
        linters: [<check>,...]

Configuration examples

The following illustrate some implementations of the above spec:

type: bundle
charmhub:
  # these fields are set to the default value to illustrate field usage
  # likely not required in most cases
  api-url: https://api.charmhub.io
  storage-url: https://storage.snapcraftcontent.com
parts:
  bundle:
    prime: ["README.md"]
bases:
  - name: ubuntu
    channel: "20.04"

A different example, with a more comprehensive base definition:

type: charm
bases:
    - build-on:
        - name: ubuntu
          channel: "20.04"
          architectures: ["amd64"]
      run-on:
        - name: ubuntu
          channel: "21.04"
          architectures: 
              - amd64
              - aarch64
              - arm64

Last updated a month ago.