Add a plugin mechanism to provide custom locator URL schemes #3937

jandubois · 2025-08-30T05:12:14Z

The template reader will attempt to call limactl-url-$SCHEME to rewrite a custom URL as either a local filename, or a URL with a supported scheme like https.

This change allows us to experiment with custom schemes, like the one requested in #3930.

Example implementation for the github: scheme is at the end. You can use:

github:ORG/REPO
github:ORG/REPO/DIR/
github:ORG/REPO/DIR/FILE
github:ORG/REPO/DIR/FILE@BRANCH

FILE defaults to lima, and files without an extension will have .yaml appended.

The default branch is determined by the GitHub API if no BRANCH is specified.

❯ limactl tmpl copy github:lima-vm/lima/templates/fedora-42 -
minimumLimaVersion: 1.1.0

base:
- template://_images/fedora-42
- template://_default/mounts

This implementation has a few differences to the one requested in #3930:

uses default branch instead of hard-coded master
uses lima.yaml instead of templates/default.yaml as the default file

I believe this implementation is more versatile, but we can discuss this below. The plugin format makes it easy to experiment.

Here is a minimalistic my: scheme to fetch default templates from the Lima repo:

❯ cat ~/bin/limactl-url-my
#!/bin/bash
echo "https://raw.githubusercontent.com/lima-vm/lima/master/templates/$1.yaml"

❯ limactl tmpl copy my:opensuse-leap -
minimumLimaVersion: 1.1.0

base:
- template://_images/opensuse-leap
- template://_default/mounts

And here is limactl-url-github. Which should become a builtin scheme (implemented in Go) once we agree on the specific semantics:

#!/bin/bash

if [ $# -ne 1 ]; then
    echo "Usage: $0 [github:]ORG/REPO[/PATH][@BRANCH]" >&2
    exit 1
fi

input="$1"

# Remove optional github: prefix
if [[ "$input" == github:* ]]; then
    input="${input#github:}"
fi

# Check for explicit branch specification with @ at the end
branch=""
if [[ "$input" == *@* ]]; then
    # Split on last @ to get branch
    branch="${input##*@}"
    input="${input%@*}"
fi

# Split the input into components
IFS='/' read -ra PARTS <<< "$input"

if [ ${#PARTS[@]} -lt 2 ]; then
    echo "Error: Input must be at least ORG/REPO" >&2
    exit 1
fi

org="${PARTS[0]}"
repo="${PARTS[1]}"

# Extract path (everything after ORG/REPO)
if [ ${#PARTS[@]} -gt 2 ]; then
    path=""
    for ((i=2; i<${#PARTS[@]}; i++)); do
        if [ -n "$path" ]; then
            path="$path/"
        fi
        path="$path${PARTS[i]}"
    done
else
    path="lima"
fi

# If path ends with /, it's a directory, so append lima
if [[ "$path" == */ ]]; then
    path="${path}lima"
fi

# If the filename (last component) has no extension, add .yaml
filename="${path##*/}"
if [[ "$filename" != *.* ]]; then
    path="$path.yaml"
fi

# Query default branch if no branch was specified
if [ -z "$branch" ]; then
    branch=$(gh repo view "$org/$repo" --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)
    if [ $? -ne 0 ] || [ -z "$branch" ]; then
        echo "Error: Failed to get default branch for $org/$repo. Make sure the repository exists and you have access." >&2
        exit 1
    fi
fi

echo "https://raw.githubusercontent.com/$org/$repo/$branch/$path"

jandubois · 2025-08-30T05:40:00Z

I just realized that the limactl-url prefix makes the names overlap with regular plugin names. Not sure if that is an issue or a feature:

❯ limactl url-github lima-vm/lima
https://raw.githubusercontent.com/lima-vm/lima/master/lima.yaml

❯ limactl url-my default
https://raw.githubusercontent.com/lima-vm/lima/master/templates/default.yaml

If we don't want this, then we need to use a longer prefix for plugins, like limactl-plugin-*. Which does not match what other commands like git or kubectl do, so I would prefer to keep it as it is. Or I guess we could use lima-url-* as a prefix for url schemes. 🤷 I think I'm fine with the overlap.

jandubois · 2025-08-30T06:07:15Z

I've just tested, and you can use tags or commit ids instead of branch names too. These all work:

❯ limactl tmpl copy github:lima-vm/lima/examples/[email protected] -
❯ limactl tmpl copy github:lima-vm/lima/examples/opensuse@74e2fda81 -

msgilligan · 2025-08-30T06:38:11Z

This looks great!

a few differences to the one requested in #3930

I did say "something like" in the request to leave room for improvement!

jandubois · 2025-08-30T20:07:21Z

I've updated the PR by refactoring the code to run subcommands with the limactl directory first on the PATH and also added a limactl template url CUSTOM_URL command (mostly for integration tests later):

❯ l tmpl url github:lima-vm/lima
https://raw.githubusercontent.com/lima-vm/lima/master/lima.yaml

AkihiroSuda · 2025-09-04T00:15:25Z

What is the remaining task to merge this PR? CI?

jandubois · 2025-09-04T01:26:10Z

What is the remaining task to merge this PR? CI?

I was planning to move to template:default style templates (and translate the existing form with a warning to the new format), but also to move the github: scheme to be builtin, implemented in Go. I was hoping to get some feedback if the semantics of the bash prototype seem correct to everyone.

Either or both could happen in separate PRs to keep the PR easier to review.

jandubois · 2025-09-04T23:36:31Z

I was planning to move to template:default style templates (and translate the existing form with a warning to the new format), but also to move the github: scheme to be builtin, implemented in Go. I was hoping to get some feedback if the semantics of the bash prototype seem correct to everyone.

I think it will be best to create separate PRs for further changes, to keep things easy for review.

I've made one more change in this PR: I've appended /usr/local/libexec/lima to the end of the PATH, so we look for plugins in the same directory we use to store external drivers. This is based on discussion in #3744 (comment).

I've noticed that we also use LIMA_DRIVERS_PATH and LIMA_TEMPLATES_PATH to define additional search locations for drivers and templates. And we look in $LIMA_HOME/_templates for templates as well. I feel like this is getting out of hand and don't want to add similar mechanisms for plugins, at least not yet. Let me know if you think otherwise.

AkihiroSuda · 2025-09-05T05:37:35Z

cmd/limactl/main.go

 		if err != nil || cmd == rootCmd {
-			// Function calls os.Exit() if it found and executed the plugin
-			runExternalPlugin(rootCmd.Context(), args[0], args[1:])
+			_ = executil.WithExecutablePath(func() error {


Why ignore err?

AkihiroSuda · 2025-09-05T05:38:02Z

cmd/limactl/template.go

 	return err
 }

+func newTemplateURLCommand() *cobra.Command {


Needs docs and tests

Docs can be added under https://deploy-preview-3972--lima-vm.netlify.app/docs/config/plugin after merging:

docs: split long pages, fix minor errors, etc. #3972

This PR is also modifying the same logic that #3973 is currently changing.

And tests should be implemented using BATS from #3969.

I'm turning this back unto "Draft" until these 3 PRs have landed because it will likely need serious refactoring by then.

jandubois · 2025-09-07T04:52:51Z

I just created another URL scheme for testing: instance: to reference the template of an already created instance:

#!/bin/bash
echo "${LIMA_HOME:-$HOME/.lima}/$1/lima.yaml"

With this you can create another instance with identical config like this (but unlike the clone command you start with a fresh disk):

❯ limactl create -y --name clone instance:default

And of course it works all the usual places: limactl tmpl validate instance:clone or limactl tmpl copy instance:default - etc.

Not sure though if it is useful enough to be builtin.

AkihiroSuda · 2025-09-08T03:06:51Z

instance:

This is quite confusing; limactl start instance:NAME should just mean starting an instance named NAME (i.e., limactl start NAME)

jandubois · 2025-09-08T04:29:46Z

instance:

This is quite confusing; limactl start instance:NAME should just mean starting an instance named NAME (i.e., limactl start NAME)

Yeah, let's not include it in Lima. I think the only scheme we want to have builtin is github.

AkihiroSuda · 2025-09-23T04:06:36Z

Needs rebase

jandubois · 2025-09-25T23:50:31Z

github:ORG/REPO
github:ORG/REPO/DIR/
github:ORG/REPO/DIR/FILE
github:ORG/REPO/DIR/FILE@BRANCH

Extension ideas:

github:ORG is the same as github:ORG/lima.yaml or github:ORG/ORG if lima.yaml repo doesn't exist
github:ORG// is the same as github:ORG, but you can now append a DIR, FILE, and BRANCH: github:mylongprojectname//templates/lima.yaml

jandubois · 2025-09-26T07:29:45Z

I think this PR is ready for review.

Still missing, but could be done in several separate PRs:

Implement builtin github: scheme in Go
Switch to template: scheme, but keep template:// working for backwards compatibility
Add BATS tests for plugins in general and url-* plugins in particular
Explain url-* plugins in the docs

Also fix the global option processing so that they are not passed on to the plugin commands. Signed-off-by: Jan Dubois <[email protected]>

The template reader will attempt to call `limactl-url-$SCHEME` to rewrite a custom URL as either a local filename, or a URL with a supported URL like https. Signed-off-by: Jan Dubois <[email protected]>

jandubois · 2025-09-29T03:12:08Z

Still missing, but could be done in several separate PRs:

Switch to template: scheme, but keep template:// working for backwards compatibility

I've made that change as well now (in a separate commit), but I think this PR is getting too big. Can we get this reviewed and merged, and do the remaining tasks in separate PRs?

pkg/limatmpl/locator.go

AkihiroSuda · 2025-09-29T06:33:22Z

README.md

 To run containers with Docker:
 ```bash
-limactl start template://docker
+limactl start template:docker


The old form should be kept until people actually begin using v2

I kind of disagree. The website should document the released version, but the README.md should correspond to the state of the branch.

Otherwise we could also not close issues until their PRs have been included in a new release, which would make the whole workflow really awkward.

I'll revert for now, but after 2.0 we should rethink our workflow, and also figure out how to have a version of the docs for the last release, and a different version for the head of master.

Regardless to our intention, people will just refer to the README in the default branch and will continue opening "I followed README but it doesn't work" issues when the content conflicts with the latest release, so we have to care about them

Regardless to our intention, people will just refer to the README in the default branch

I think the way to deal with that is to remove end-user instructions from the README and point them to the docs. There is no reason to repeat usage documentation in it.

README

Lima is Linux Machines running in a VM...

How to install and use?

Please read the [Documentation] and follow the [Installation] instructions.

Community channels

New releases on GitHub

GitHub Discussions and Issues

Slack

Community meetings (maybe?)

Social media (if we start posting there)

Developing Lima

Required tools and their version

How to build

How to run tests

License

I still prefer to keep the "TLDR" abstract in README.md.
First comers do not want to access the website when they do not even know what it is all about.

The old style template://name URLs are malformed because they do not contain a valid AUTHORITY (host name), but treat the host name as part of the path. They are still fully supported, but will emit a warning. Signed-off-by: Jan Dubois <[email protected]>

AkihiroSuda

Thanks

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

AkihiroSuda · 2025-10-04T03:01:57Z

On the second thought, a locator plugin should return the YAML contents, not HTTPS URL, so as to support non-HTTP and non-local remotes

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois mentioned this pull request Aug 30, 2025

Shorthand URL syntax for 3rd-party templates on GitHub #3930

Open

jandubois force-pushed the custom-url-schemes branch 2 times, most recently from 00bb585 to 824daed Compare August 30, 2025 05:31

jandubois force-pushed the custom-url-schemes branch from 824daed to 6e87a32 Compare August 30, 2025 20:05

jandubois force-pushed the custom-url-schemes branch from 6e87a32 to ad26a40 Compare August 30, 2025 20:28

AkihiroSuda added this to the v2.0.0 milestone Sep 1, 2025

jandubois force-pushed the custom-url-schemes branch from ad26a40 to f6ceb58 Compare September 4, 2025 23:29

jandubois force-pushed the custom-url-schemes branch 2 times, most recently from 5a1ab38 to 6032d5f Compare September 4, 2025 23:59

jandubois marked this pull request as ready for review September 5, 2025 01:19

AkihiroSuda reviewed Sep 5, 2025

View reviewed changes

jandubois marked this pull request as draft September 5, 2025 23:19

jandubois mentioned this pull request Sep 25, 2025

Add Garden Linux template #4086

Open

AkihiroSuda mentioned this pull request Sep 26, 2025

Third-party template discovery #4097

Closed

jandubois force-pushed the custom-url-schemes branch 3 times, most recently from 5dde020 to 5d72cc0 Compare September 26, 2025 07:02

jandubois marked this pull request as ready for review September 26, 2025 07:25

Simplify plugin support code

1055f75

Also fix the global option processing so that they are not passed on to the plugin commands. Signed-off-by: Jan Dubois <[email protected]>

jandubois force-pushed the custom-url-schemes branch 2 times, most recently from d306d12 to 97a9d84 Compare September 28, 2025 20:20

Add a plugin mechanism to provide custom locator URL schemes

1958c01

The template reader will attempt to call `limactl-url-$SCHEME` to rewrite a custom URL as either a local filename, or a URL with a supported URL like https. Signed-off-by: Jan Dubois <[email protected]>

jandubois force-pushed the custom-url-schemes branch from 97a9d84 to 8ed0180 Compare September 28, 2025 21:14

jandubois requested a review from AkihiroSuda September 29, 2025 03:12

AkihiroSuda reviewed Sep 29, 2025

View reviewed changes

pkg/limatmpl/locator.go Outdated Show resolved Hide resolved

AkihiroSuda added the impact/changelog label Sep 29, 2025

jandubois force-pushed the custom-url-schemes branch from 8ed0180 to e46309e Compare September 29, 2025 06:25

AkihiroSuda reviewed Sep 29, 2025

View reviewed changes

jandubois force-pushed the custom-url-schemes branch from e46309e to 942bb17 Compare September 29, 2025 06:34

jandubois force-pushed the custom-url-schemes branch from 942bb17 to 677fa1f Compare September 29, 2025 06:42

AkihiroSuda approved these changes Sep 29, 2025

View reviewed changes

AkihiroSuda merged commit 70a3f13 into lima-vm:master Sep 29, 2025
61 of 63 checks passed

jandubois deleted the custom-url-schemes branch September 29, 2025 23:06

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

9765df4

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

59a60cd

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois mentioned this pull request Oct 4, 2025

Implement custom github: URL scheme in Go #4134

Merged

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

ba49274

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

AkihiroSuda mentioned this pull request Oct 4, 2025

A locator plugin should return the YAML contents, not HTTPS URL #4135

Closed

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

5ae31b5

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

4e3ca40

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

00f615e

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois added a commit to jandubois/lima that referenced this pull request Oct 4, 2025

Implement custom github URL scheme in Go

1302d70

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

jandubois added a commit to jandubois/lima that referenced this pull request Oct 5, 2025

Implement custom github URL scheme in Go

4faf738

This is a reimplementation of the bash code in lima-vm#3937 (comment) Signed-off-by: Jan Dubois <[email protected]>

Add a plugin mechanism to provide custom locator URL schemes #3937

Add a plugin mechanism to provide custom locator URL schemes #3937

Uh oh!

Conversation

jandubois commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jandubois commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jandubois commented Aug 30, 2025

Uh oh!

msgilligan commented Aug 30, 2025

Uh oh!

jandubois commented Aug 30, 2025

Uh oh!

AkihiroSuda commented Sep 4, 2025

Uh oh!

jandubois commented Sep 4, 2025

Uh oh!

jandubois commented Sep 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jandubois commented Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AkihiroSuda commented Sep 8, 2025

Uh oh!

jandubois commented Sep 8, 2025

Uh oh!

AkihiroSuda commented Sep 23, 2025

Uh oh!

jandubois commented Sep 25, 2025

Uh oh!

jandubois commented Sep 26, 2025

Uh oh!

jandubois commented Sep 29, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

README

How to install and use?

Community channels

Developing Lima

Required tools and their version

How to build

How to run tests

License

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AkihiroSuda commented Oct 4, 2025

Uh oh!

Uh oh!

jandubois commented Aug 30, 2025 •

edited

Loading

jandubois commented Aug 30, 2025 •

edited

Loading

jandubois commented Sep 7, 2025 •

edited

Loading