Remote Repositories
Dagger supports the use of remote repositories in two distinct ways:
- As directory arguments to Dagger Functions
- As Dagger modules
In both cases, Dagger supports the use of HTTP and SSH protocols for accessing remote repositories, compatible with all major Git hosting platforms such as GitHub, GitLab, BitBucket, Azure DevOps, Codeberg, and Sourcehut. For SSH references ("refs"), Dagger employs a unified authentication approach.
Use remote repositories as directory arguments
Dagger Functions that accept directory arguments are equally comfortable receiving local filesystem paths or remote Git repository references. In both cases, the CLI will convert it to an object referencing the contents of that filesystem path or Git repository location, and pass the resulting Directory
object as argument to the Dagger Function.
Supported protocols and schemes
Dagger supports the following reference schemes for directory arguments:
Protocol | Scheme | Public repositories | Private repositories | Example |
---|---|---|---|---|
HTTP(S) | Git HTTP | Supported | In progress | https://github.com/username/repo.git[#version[:subdir]] |
SSH | Explicit | Supported | Supported | ssh://git@github.com/username/repo.git[#version[:subdir]] |
SSH | SCP-like | Supported | Supported | git@github.com:username/repo.git[#version[:subdir]] |
Dagger provides additional flexibility in referencing directory arguments through the following options:
- Version specification: Add
#version
to target a particular version of the repository. This can be a tag, branch name, or full commit hash. If omitted, the default branch is used. - Monorepo support: Append
:subpath
after the version specification to access a specific subdirectory within the repository. Note that specifying a version is mandatory when including a subpath.
When referencing a specific subdirectory (subpath) within a repository, you must always include a version specification. The format is always #version:subpath
.
Examples
Here is an example of passing a remote repository (Dagger's open-source repository) over HTTPS as a Directory
argument:
dagger core container \
from --address=alpine:latest \
with-directory --path=/src --directory=https://github.com/dagger/dagger \
with-exec --args="ls","/src" \
stdout
In addition to supporting HTTP(S) access for public repositories, Dagger also supports the use of SSH for both public and private repositories. Note that this requires SSH authentication to be properly configured on your Dagger host. Here is the same example, this time using SSH:
dagger core container \
from --address=alpine:latest \
with-directory --path=/src --directory=ssh://git@github.com/dagger/dagger \
with-exec --args="ls","/src" \
stdout
Consume Dagger modules from remote repositories
Modules don't need to be installed locally. Dagger lets you consume modules from both public and private Git repositories as well.
Supported protocols and schemes
Dagger supports various reference schemes for Dagger modules, as below:
Protocol | Scheme | Public repositories | Private repositories | Example |
---|---|---|---|---|
HTTP(S) | Go-like ref style | Supported | In progress | github.com/username/repo[/subdir][@version] |
HTTP(S) | Git HTTP style | Supported | In progress | https://github.com/username/repo.git[/subdir][@version] |
SSH | SCP-like | Supported | Supported | git@github.com:username/repo.git[/subdir][@version] |
SSH | Explicit SSH | Supported | Supported | ssh://git@github.com/username/repo.git[/subdir][@version] |
Dagger provides additional flexibility in referencing modules through the following options:
- The
.git
extension is optional for HTTP refs or explicit SSH refs, except for GitLab, when referencing modules stored on a private repo or private subgroup. - Monorepo support: Append
/subpath
to access a specific subdirectory within the repository. - Version specification: Add
@version
to target a particular version of the module. This can be a tag, branch name, or full commit hash. If omitted, the default branch is used.
Examples
Here is an example of using a Go builder Dagger module from a public repository over HTTPS:
dagger -m github.com/kpenfound/dagger-modules/golang@v0.2.0 call \
build --source=https://github.com/dagger/dagger --args=./cmd/dagger \
export --path=./build
Here is the same example using SSH authentication. Note that this requires SSH authentication to be properly configured on your Dagger host).
dagger -m git@github.com:kpenfound/dagger-modules/golang@v0.2.0 call \
build --source=https://github.com/dagger/dagger --args=./cmd/dagger \
export --path=./build
Configuring SSH authentication
Dagger mounts the socket specified by your host's SSH_AUTH_SOCK
environment variable to the Dagger Engine. This is essential for SSH refs, as most Git servers use your SSH key for authentication and tracking purposes, even when cloning public repositories.
This means that you must ensure that the SSH_AUTH_SOCK
environment variable is properly set in your environment when using SSH refs with Dagger.
Read detailed instructions on setting up SSH authentication, including how to generate SSH keys, start the SSH agent, and add your keys.
Best practices
For quick and easy referencing:
- Copy the repository ref from your preferred Git server's UI.
- To specify a particular version or commit, append
#version
(for directory arguments) or@version
(for modules). - To target a specific directory within the repository, use the format
#version:subpath
(for directory arguments) or add a/subpath
(for modules). Remember that the version is mandatory when specifying a subpath.
Known limitations and workarounds
This section outlines current limitations and provides workarounds for common issues. We're actively working on improvements for these areas.
Windows is not supported
Currently, SSH refs are fully supported on UNIX-based systems (Linux and macOS). Windows support is under development. Track progress and contribute to the discussion in our GitHub issue for Windows support.
Multiple SSH keys may cause SSH forwarding to fail
SSH forwarding may fail when multiple keys are loaded in your SSH agent. This is under active investigation in our GitHub issue. Until this is resolved, the following workaround may be used:
- Clear all loaded keys:
ssh-add -D
- Add back only the required key:
ssh-add /path/to/key
Environment variables are not automatically expanded
Shell expansion characters (e.g., ~
) in the SSH_AUTH_SOCK
environment variable are not automatically expanded. This is under active investigation in our GitHub issue. Until this is resolved, the workaround is to use the full path instead of ~
when setting SSH_AUTH_SOCK
.
SSH_AUTH_SOCK
paths are not always handled correctly
The Dagger CLI incorrectly handles the SSH_AUTH_SOCK
path by converting it to a relative path from the Dagger CLI's current working directory. This can lead to issues with SSH forwarding, especially when the socket path is in the same directory tree as the working directory. A fix for this issue is in progress
Until this is resolved, ensure that the SSH_AUTH_SOCK
path is not on the same path as your current working directory (except for the root directory '/'). A simple workaround is to create a symlink in /var/run
or /tmp
that points to the value of SSH_AUTH_SOCK
, and then export this new path as SSH_AUTH_SOCK.