Dagger Cloud

Identity verification

Dagger Cloud requires a GitHub account for identity verification. If you don't have one, register for a free GitHub account before proceeding.

Traces

Create a Dagger Cloud organization

1. Sign up for Dagger Cloud by selecting a plan on the Dagger website. Dagger Cloud includes plans for both individuals and teams. Click Continue with GitHub to log in with your GitHub account.

2. After authorizing Dagger Cloud for your GitHub account, you'll create your organization.

   Naming your organization

   Organization names may contain alphanumeric characters and dashes and are unique across Dagger Cloud. We recommend using your company name or team name for your organization.

3. Review and select a Dagger Cloud subscription plan.

4. If you selected the Team plan:

   1. You will be presented with the option to add teammates to your Dagger Cloud account. This step is optional and not available in the Individual plan.

   2. You will then enter your payment information. After your free 14 day trial completes, you will be automatically subscribed to the Dagger Cloud Team plan.

5. Click Go to dashboard. The next step walks you through how to send telemetry to Dagger Cloud.

Connect to Dagger Cloud

The next step is to connect to Dagger Cloud from your local development environment or from your CI environment.

Connect from your local development host

You can visualize and debug your local Dagger pipeline runs with Dagger Cloud to identify issues before pushing them to CI.

To configure for local development, run the dagger login command.

Multiple Dagger Cloud organizations

To use Dagger Cloud locally when you have multiple organizations linked to your account, you must use dagger login ORGANIZATION-NAME instead.

The Dagger CLI will invite you to authenticate your device by displaying a link containing a unique key. Click the link in your browser, and verify that you see the same key in the Dagger Cloud Web interface.

$ dagger login
Browser opened to: https://auth.dagger.cloud/activate?user_code=XXXX-YYYY
Confirmation code: XXXX-YYYY

Once you confirm your authentication code, your Dagger CLI will be authenticated and you can now visualize and debug your local Dagger pipeline runs.

info

If you do not want to use dagger login, set your Dagger Cloud token as an environment variable. For example:

export DAGGER_CLOUD_TOKEN={your token}

Connect from your CI environment

To connect to Dagger Cloud from a CI environment, you require a Dagger Cloud token. Dagger Cloud creates this token automatically when you sign up.

To find your token, browse to the Organization Settings page, by clicking your profile photo in the left sidebar and then clicking Organization Settings. Select the Configuration tab. You can also use this URL pattern: https://dagger.cloud/{Your Org Name}/settings?tab=configuration

warning

If you regenerate your token, you must replace the token wherever you've referenced it. To reduce operational interruptions, only regenerate your token if it has leaked.

Once you have your token, you can use it to connect Dagger Cloud with your CI environment. The general procedure is:

• Add your Dagger Cloud token to your CI environment.
  • Store the Dagger Cloud token as a secret with your CI environment.
    Keep your Dagger Cloud token private

    You must store the Dagger Cloud token as a secret (not plaintext) with your CI environment and reference it in your CI workflow. Using a secret is recommended to protect your Dagger Cloud account from being used by forks of your project. We provide links in the steps below for configuring secrets with popular CI tools.

  • Add the secret to your CI environment as a variable named DAGGER_CLOUD_TOKEN.
• For Team plan subscribers with ephemeral CI runners only: Add a wait step (example below) for the Docker configuration to allow Dagger to push cache volumes to the experimental Dagger Cloud distributed cache. Subscribers on the Individual plan do not have access to the experimental distributed cache and do not need to add this step.
• If you are using GitHub Actions, install the Dagger Cloud GitHub app for GitHub Checks. This app adds a GitHub check to your pull requests. Each check links to the corresponding pipeline visualization in Dagger Cloud.

You can use Dagger Cloud whether you're hosting your own CI runners and infrastructure or using hosted/SaaS runners.

danger

When using self-hosted CI runners on AWS infrastructure, NAT Gateways are a common source of unexpected network charges. It's advisable to setup an Amazon S3 Gateway for these cases. Refer to the AWS documentation for detailed information on how to do this.

GitHub Actions

1. Create a new secret for your GitHub repository named DAGGER_CLOUD_TOKEN, and set it to the value of the token obtained in Step 1. Refer to the GitHub documentation on creating repository secrets.

2. Update your GitHub Actions workflow and add the secret to the Dagger pipeline step as an environment variable. The environment variable must be named DAGGER_CLOUD_TOKEN and can be referenced in the workflow using the format DAGGER_CLOUD_TOKEN: ${{ secrets.DAGGER_CLOUD_TOKEN }}. Refer to the GitHub documentation on using secrets in a workflow.

   See an example of a sample GitHub Actions workflow file

3. Install the Dagger Cloud GitHub App. Once installed, GitHub automatically adds a new check for your GitHub pull requests, with a link to see CI status for each workflow job in Dagger Cloud.

GitLab CI

1. Create a new CI/CD project variable in your GitLab project named DAGGER_CLOUD_TOKEN, and set it to the value of the token obtained in Step 1. Ensure that you configure the project variable to be masked and protected. Refer to the GitLab documentation on creating CI/CD project variables and CI/CD variable security.

2. Update your GitLab CI workflow and add the variable to your CI environment. The environment variable must be named DAGGER_CLOUD_TOKEN. Refer to the GitLab documentation on using CI/CD variables.

   See an example of a sample GitLab workflow file

3. For Team plan subscribers with ephemeral CI runners only: Update your GitLab CI workflow (example below) and adjust the docker stop timeout period so that Docker waits longer before killing the Dagger container, to give it more time to push data to the Dagger Cloud cache. Refer to the Docker documentation on the docker stop command.

CircleCI

1. Create a new environment variable in your CircleCI project named DAGGER_CLOUD_TOKEN and set it to the value of the token obtained in Step 1. Refer to the CircleCI documentation on creating environment variables for a project.

2. For Team plan subscribers with ephemeral CI runners only: Update your CircleCI workflow (example below) and adjust the docker stop timeout period so that Docker waits longer before killing the Dagger container, to give it more time to push data to the Dagger Cloud cache. Refer to the Docker documentation on the docker stop command.

3. For GitHub, GitLab or Atlassian Bitbucket source code repositories only: Update your CircleCI workflow and add the following pipeline values to the CI environment. Refer to the CircleCI documentation on using pipeline values.

   GitHub:

   environment:
     CIRCLE_PIPELINE_NUMBER: << pipeline.number >>

   GitLab:

   environment:
     CIRCLE_PIPELINE_NUMBER: << pipeline.number >>
     CIRCLE_PIPELINE_TRIGGER_LOGIN: << pipeline.trigger_parameters.gitlab.user_username >>
     CIRCLE_PIPELINE_REPO_URL: << pipeline.trigger_parameters.gitlab.repo_url >>
     CIRCLE_PIPELINE_REPO_FULL_NAME: << pipeline.trigger_parameters.gitlab.repo_name >>

   Atlassian BitBucket:

   environment:
     CIRCLE_PIPELINE_NUMBER: << pipeline.number >>

   See an example of a sample CircleCI workflow

Jenkins

1. Configure a Jenkins credential named DAGGER_CLOUD_TOKEN and set it to the value of the token obtained in Step 1. Refer to the Jenkins documentation on creating credentials and credential security.

2. Update your Jenkins Pipeline and add the variable to the CI environment. The environment variable must be named DAGGER_CLOUD_TOKEN and can be referenced in the Pipeline environment using the format DAGGER_CLOUD_TOKEN = credentials('DAGGER_CLOUD_TOKEN'). Refer to the Jenkins documentation on handling credentials.

   See an example of a sample Jenkins Pipeline

note

• This Jenkins Pipeline assumes that the Dagger CLI is pre-installed on the Jenkins runner(s), together with other required dependencies.
• If you use the same Jenkins server for more than one Dagger Cloud organization, create distinct credentials for each organization and link them to their respective Dagger Cloud tokens.
• Typically, Jenkins servers are non-ephemeral and therefore it is not necessary to adjust the docker stop timeout.

Argo Workflows

1. Create a new Kubernetes secret named dagger-cloud and set it to the value of the token obtained in Step 1. An example command to achieve this is shown below (replace the TOKEN placeholder with your actual token value). Refer to the Kubernetes documentation on creating secrets.

   kubectl create secret generic dagger-cloud --from-literal=token=TOKEN

2. Update your Argo Workflows specification and add the secret as an environment variable. The environment variable must be named DAGGER_CLOUD_TOKEN.

   See an example of a sample Argo Workflows specification

Test the integration

The next step is to test the integration with Dagger Cloud.

Test from your local development host

1. In your terminal, call a Dagger Function. You will see a Dagger Cloud URL printed in the terminal.
2. Click on the URL to view details of the run in Dagger Cloud.

info

Dagger 0.11.0 adds support for visualizing Dagger functions but does not yet print the Dagger Cloud URL for the pipeline run in the CLI output. We're adding this soon.

dagger -m github.com/shykes/daggerverse/hello@v0.3.0 call hello

Test from your CI environment

Trigger your CI workflow by pushing a commit or opening a pull request.

Organizations

A member account grants a person access to log in to a Dagger Cloud organization to diagnose pipeline failures and collaborate on changes. Member information shown on the All Runs and All Changes pages is populated by the VCS you have integrated with Dagger Cloud. Deleting a member of a Dagger Cloud organization will not remove their runs and changes from Dagger Cloud.

important

You must hold the Admin role of a Dagger Cloud organization to administer members. You cannot change a member's role. Please contact Dagger Support via the in-app messenger for assistance if you need to change a member's role. This functionality is coming soon.

Roles and permissions

In Dagger Cloud, users can have one of two roles: Admin or Member. The Admin role is not a superset of the Member role. If a user needs to administer an organization and view Dagger pipeline runs, ensure that the user also has the Member role.

Actions	Admin	Member
View Dagger pipeline runs and changes		✓
View members of an org	✓	✓
Invite new members to an org	✓
Delete an existing member from an org	✓

You cannot change a member's role at this time. Please contact Dagger via the support messenger in Dagger Cloud if you need assistance.

Cache volumes

warning

Dagger Cloud's distributed caching feature is currently experimental.

Dagger Cloud automatically detects and creates cache volumes when they are declared in your Dagger pipeline or custom functions.

Your cache volumes will appear in the UI within a few minutes after your Dagger function(s) have completed execution. If you don't see them in the UI, ensure you've referenced the volumes correctly in your code and that you've set up your CI or local development workflows to push the cache volumes to Dagger Cloud.

To see your cache volumes, browse to the Organization Settings page of the Dagger Cloud dashboard (accessible by clicking your user profile icon in the Dagger Cloud interface) and navigate to the Configuration tab. You should see the newly-created volumes listed and enabled.

You can create as many volumes as needed and manage them from the Configuration tab of your Dagger Cloud organization page.

The volumes cache is shared across pipelines and runs, within the same Dagger Cloud organization. This implies that users in the same organization share the same volumes cache. The cache key for the volumes cache is bucket / organization-name / volume-name, where the volume name is set by the user using the Dagger API. Manifests of the layers cache are sent to Dagger Cloud to support merging layers between runs (not supported by Buildkit).

important

No cache data is shared across organizations. For more information on security, visit the Dagger Trust Center.

tip

If you've configured cache volumes for the first time in a local development environment, call your Dagger function via the Dagger CLI and then run the command docker container stop -t 300 "$(docker container list --filter 'name=^dagger-engine-*' -q)". This step ensures your new cache volumes populate to Dagger Cloud during the engine shutdown phase. You only need to do this the first time you use Dagger Cloud locally with cache volumes or when you add new cache volumes in your Dagger pipeline.