Skip to main content

How to use secrets

Most operations in client support handling secrets (see Interacting with the client). More specifically, you can:

  • Write a secret to a file;
  • Read a secret from a file;
  • Read a secret from an environment variable;
  • Read a secret from the output of a command;
  • Use a secret as the input of a command.


The simplest use case is reading from an environment variable:

dagger.#Plan & {
client: env: GITHUB_TOKEN: dagger.#Secret


You may need to trim the whitespace, especially when reading from a file:

dagger.#Plan & {
// Path may be absolute, or relative to current working directory
client: filesystem: ".registry": read: {
// CUE type defines expected content
contents: dagger.#Secret
actions: {
registry: core.#TrimSecret & {
input: client.filesystem.".registry".read.contents
pull: docker.#Pull & {
source: ""
auth: {
username: "_token_"
secret: registry.output


There’s many ways to store encrypted secrets in your git repository. If you use SOPS, here's a simple example where you can access keys from an encrypted yaml file:

myToken: ENC[AES256_GCM,data:AlUz7g==,iv:lq3mHi4GDLfAssqhPcuUIHMm5eVzJ/EpM+q7RHGCROU=,tag:dzbT5dEGhMnHbiRTu4bHdg==,type:str]
sops: ...
dagger.#Plan & {
client: commands: sops: {
name: "sops"
args: ["-d", "./secrets.yaml"]
stdout: dagger.#Secret

actions: {
// Makes the yaml keys easily accessible
secrets: core.#DecodeSecret & {
input: client.commands.sops.stdout
format: "yaml"

run: docker.#Run & {
mounts: secret: {
dest: "/run/secrets/token"
contents: secrets.output.myToken.contents
// Do something with `/run/secrets/token`