Secrets Integration

Dagger natively supports reading confidential information ("secrets"), such as passwords, API keys, SSH keys, and access tokens, from multiple secret providers and has built-in safeguards to ensure that secrets do not leak into the open.

These secrets can be sourced from different secret providers, including the host environment, the host filesystem, the result of host command execution, and external secret managers 1Password, Vault, and AWS Secrets Manager/Parameter Store.

important

Dagger has built-in safeguards to ensure that secrets are used without exposing them in plaintext logs, writing them into the filesystem of containers you're building, or inserting them into the cache. This ensures that sensitive data does not leak - for example, in the event of a crash.

Here's an example of a workflow that receives and uses a GitHub personal access token as a secret:

Go

package main

import (
	"context"
	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

func (m *MyModule) GithubApi(
	ctx context.Context,
	token *dagger.Secret,
) (string, error) {
	return dag.Container().
		From("alpine:3.17").
		WithSecretVariable("GITHUB_API_TOKEN", token).
		WithExec([]string{"apk", "add", "curl"}).
		WithExec([]string{"sh", "-c", `curl "https://api.github.com/repos/dagger/dagger/issues" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $GITHUB_API_TOKEN"`}).
		Stdout(ctx)
}

Python

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    @function
    async def github_api(
        self,
        token: dagger.Secret,
    ) -> str:
        return await (
            dag.container(platform=dagger.Platform("linux/amd64"))
            .from_("alpine:3.17")
            .with_secret_variable("GITHUB_API_TOKEN", token)
            .with_exec(["apk", "add", "curl"])
            .with_exec(
                [
                    "sh",
                    "-c",
                    (
                        'curl "https://api.github.com/repos/dagger/dagger/issues"'
                        ' --header "Authorization: Bearer $GITHUB_API_TOKEN"'
                        ' --header "Accept: application/vnd.github+json"'
                    ),
                ]
            )
            .stdout()
        )

TypeScript

import { dag, object, func, Secret } from "@dagger.io/dagger"

@object()
class MyModule {
  @func()
  async githubApi(token: Secret): Promise<string> {
    return await dag
      .container()
      .from("alpine:3.17")
      .withSecretVariable("GITHUB_API_TOKEN", token)
      .withExec(["apk", "add", "curl"])
      .withExec([
        "sh",
        "-c",
        `curl "https://api.github.com/repos/dagger/dagger/issues" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $GITHUB_API_TOKEN"`,
      ])
      .stdout()
  }
}

PHP

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\{DaggerObject, DaggerFunction};
use Dagger\Secret;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    public function githubApi(Secret $token): string
    {
        return dag()
            ->container()
            ->from('alpine:3.17')
            ->withSecretVariable('GITHUB_API_TOKEN', $token)
            ->withExec(['apk', 'add', 'curl'])
            ->withExec([
                'sh',
                '-c',
                'curl "https://api.github.com/repos/dagger/dagger/issues"'
                . ' --header "Authorization: Bearer $GITHUB_API_TOKEN"'
                . ' --header "Accept: application/vnd.github+json"',
            ])
            ->stdout();
    }
}

Java

package io.dagger.modules.mymodule;

import static io.dagger.client.Dagger.dag;

import io.dagger.client.exception.DaggerQueryException;
import io.dagger.client.Secret;
import io.dagger.module.annotation.Function;
import io.dagger.module.annotation.Object;
import java.util.List;
import java.util.concurrent.ExecutionException;

@Object
public class MyModule {
  @Function
  public String githubApi(Secret token) throws ExecutionException, DaggerQueryException, InterruptedException {
    return dag().container()
        .from("alpine:3.17")
        .withSecretVariable("GITHUB_API_TOKEN", token)
        .withExec(List.of("apk", "add", "curl"))
        .withExec(
            List.of(
                "sh",
                "-c",
                "curl \"https://api.github.com/repos/dagger/dagger/issues\""
                    + " --header \"Authorization: Bearer $GITHUB_API_TOKEN\""
                    + " --header \"Accept: application/vnd.github+json\""))
        .stdout();
  }
}

Host environment

The secret can be passed from the host environment via the env provider:

Files

Secrets can also be passed from host files via the file provider (shown below) or from host command output via the cmd provider:

Hashicorp Vault and 1Password

Secrets can also be read from external secret managers, such as Vault (vault):

dagger call github-api --token=vault://credentials.github

Here is the same example, but using 1Password as the secret provider. The secret is passed from 1Password via the op provider. This requires the Dagger CLI to be authenticated with 1Password, which can be done by running op signin in the terminal.

dagger call github-api --token=op://infra/github/credential

AWS Secrets Manager and Parameter Store

Secrets can also be read from AWS Secrets Manager and AWS Systems Manager Parameter Store using the aws provider. The provider automatically detects which service to use based on the path format.

AWS Secrets Manager

Use the aws:// scheme with a secret name to retrieve secrets from AWS Secrets Manager:

dagger call github-api --token=aws://prod/github/token

For JSON secrets, extract a specific field using the field query parameter:

dagger call database --password=aws://prod/database/credentials?field=password

Additional query parameters:

• region: Override the default AWS region (e.g., aws://my-secret?region=us-west-2)
• version: Retrieve a specific version by version ID (e.g., aws://my-secret?version=uuid-version-id)
• stage: Retrieve a specific version stage (e.g., aws://my-secret?stage=AWSPREVIOUS)

AWS Systems Manager Parameter Store

Use the aws:// scheme with a path starting with / to retrieve parameters from Parameter Store:

dagger call app --api-key=aws:///prod/api-key

SecureString parameters are automatically decrypted.

Authentication

The AWS provider uses the AWS SDK default credential chain, which checks for credentials in the following order:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. Shared credentials file (~/.aws/credentials)
3. IAM role credentials (when running on EC2, ECS, Lambda, etc.)

Configure the default region using the AWS_REGION environment variable or the region query parameter.

note

The AWS provider only reads secrets from AWS services. Secret creation and management should be done using the AWS CLI, AWS Console, or infrastructure-as-code tools like Terraform or CloudFormation.