Feature Request: Allow declaring canister IDs in `icp.yaml`

[q-uint]

There is currently no way to associate an existing canister ID with a project canister in icp.yaml. The only way to get a mapping is to have the CLI create the canister itself, which writes to .icp/data/mappings/<env>.ids.json.

This is a problem when:

• A canister was created outside the CLI (e.g. via dfx, NNS proposal, or another tool) and you want to adopt it into an icp project.
• You clone a repo and want to deploy to an existing canister without manually creating internal state files.
• You want canister IDs to be version-controlled alongside the rest of the project config.

Right now you have to manually create .icp/data/mappings/<env>.ids.json with the correct format, which is undocumented and fragile.

Proposed addition to the canister manifest:

canisters:
  - name: frontend
    ids:
      ic: "vmenl-oyaaa-aaaax-qaa2a-cai"
    recipe:
      type: "@dfinity/asset-canister@v2.1.0"

This would make icp.yaml the single source of truth for project configuration, which is what you'd expect from a declarative manifest.

[raymondk]

Hi @q-uint - as always thanks for the feedback!

For now, I think the best way to go is to edit the files manually. We will add more documentation around the structure of the mapping files.
At the moment we have a clean separation in the configuration:

• How to build the canisters
• Environment definitions
• canister id mappings per environment

I'm not at fan of putting the canister ids in the main configuration file like you suggest because it mixes the environment and canister definition. It make more sense to include the mapping in the environment definition but it's a little odd to mix this config because the local configuration is ephemeral and changes every time you launch stop/start the network.

Another idea that was floated is to add a command like:

icp canister link <canister-name> <environment-name> <canister-id>
# or
icp env <environment-name> link <canister-name>  <canister-id>

The idea being that you would use the cli to manage configuration files for your environment.
Since the only thing those commands would do is edit a pretty basic mapping file, I would rather wait a little bit more to see how cloud engines and the swiss subnet evolve before adding more commands.

Happy to hear your thoughts as always.