Skip to main content

Remote Taskfiles (#1317)

caution

All experimental features are subject to breaking changes and/or removal at any time. We strongly recommend that you do not use these features in a production environment. They are intended for testing and feedback only.

info

To enable this experiment, set the environment variable: TASK_X_REMOTE_TASKFILES=1. Check out our guide to enabling experiments for more information.

This experiment allows you to specify a remote Taskfile URL when including a Taskfile. For example:

version: '3'

includes:
  my-remote-namespace: https://raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml

This works exactly the same way that including a local file does. Any tasks in the remote Taskfile will be available to run from your main Taskfile via the namespace my-remote-namespace. For example, if the remote file contains the following:

version: '3'

tasks:
  hello:
    silent: true
    cmds:
      - echo "Hello from the remote Taskfile!"

and you run task my-remote-namespace:hello, it will print the text: "Hello from the remote Taskfile!" to your console.

The Taskfile location is processed by the templating system, so you can reference environment variables in your URL if you need to add authentication. For example:

version: '3'

includes:
  my-remote-namespace: https://{{.TOKEN}}@raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml

TOKEN=my-token task my-remote-namespace:hello will be resolved by Task to https://my-token@raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml

Git nodes​

You can also include a Taskfile from a Git node. We currently support ssh-style and http / https addresses like git@example.com/foo/bar.git//Taskfiles.yml?ref=v1 and https://example.com/foo/bar.git//Taskfiles.yml?ref=v1.

You need to follow this pattern : <baseUrl>.git//<path>?ref=<ref>. The ref parameter, optional, can be a branch name or a tag, if not provided it'll pick up the default branch. The path is the path to the Taskfile in the repository.

If you want to use the SSH protocol, you need to make sure that your ssh-agent has your private ssh keys added so that they can be used during authentication.

Security​

Running commands from sources that you do not control is always a potential security risk. For this reason, we have added some checks when using remote Taskfiles:

  1. When running a task from a remote Taskfile for the first time, Task will print a warning to the console asking you to check that you are sure that you trust the source of the Taskfile. If you do not accept the prompt, then Task will exit with code 104 (not trusted) and nothing will run. If you accept the prompt, the remote Taskfile will run and further calls to the remote Taskfile will not prompt you again.
  2. Whenever you run a remote Taskfile, Task will create and store a checksum of the file that you are running. If the checksum changes, then Task will print another warning to the console to inform you that the contents of the remote file has changed. If you do not accept the prompt, then Task will exit with code 104 (not trusted) and nothing will run. If you accept the prompt, the checksum will be updated and the remote Taskfile will run.

Sometimes you need to run Task in an environment that does not have an interactive terminal, so you are not able to accept a prompt. In these cases you are able to tell task to accept these prompts automatically by using the --yes flag. Before enabling this flag, you should:

  1. Be sure that you trust the source and contents of the remote Taskfile.
  2. Consider using a pinned version of the remote Taskfile (e.g. A link containing a commit hash) to prevent Task from automatically accepting a prompt that says a remote Taskfile has changed.

Task currently supports both http and https URLs. However, the http requests will not execute by default unless you run the task with the --insecure flag. This is to protect you from accidentally running a remote Taskfile that is via an unencrypted connection. Sources that are not protected by TLS are vulnerable to man-in-the-middle attacks and should be avoided unless you know what you are doing.

Caching & Running Offline​

Whenever you run a remote Taskfile, the latest copy will be downloaded from the internet and cached locally. If for whatever reason, you lose access to the internet, you will still be able to run your tasks by specifying the --offline flag. This will tell Task to use the latest cached version of the file instead of trying to download it. You are able to use the --download flag to update the cached version of the remote files without running any tasks. You are able to use the --clear-cache flag to clear all cached version of the remote files without running any tasks.

By default, Task will timeout requests to download remote files after 10 seconds and look for a cached copy instead. This timeout can be configured by setting the --timeout flag and specifying a duration. For example, --timeout 5s will set the timeout to 5 seconds.

By default, the cache is stored in the Task temp directory, represented by the TASK_TEMP_DIR environment variable You can override the location of the cache by setting the TASK_REMOTE_DIR environment variable. This way, you can share the cache between different projects.