GitHub Actions

Dagger provides a GitHub Action that can be used in any GitHub Actions workflow to call one or more Dagger Functions on specific events, such as a new commit.

How it works

When running a CI pipeline with Dagger using a standard GitHub Actions runner, the general workflow looks like this:

1. GitHub receives a workflow trigger based on a repository event.
2. GitHub begins processing the jobs and steps in the workflow.
3. GitHub finds the "Dagger for GitHub" action and passes control to it.
4. The "Dagger for GitHub" action calls the Dagger CLI with the specified sub-command, module, function name, and arguments.
5. The Dagger CLI attempts to find an existing Dagger Engine or spins up a new one inside the GitHub Actions runner.
6. The Dagger CLI executes the specified sub-command and sends telemetry to Dagger Cloud if the DAGGER_CLOUD_TOKEN environment variable is set.
7. The workflow completes with success or failure. Logs appear in GitHub as usual.

Prerequisites

• A GitHub repository

Examples

The following example demonstrates how to call a Dagger Function on a standard GitHub runner in a GitHub Actions workflow.

.github/workflows/dagger.yml

name: dagger
on:
  push:
    branches: [main]

jobs:
  hello:
    name: hello
    runs-on: ubuntu-latest
    steps:
      - name: Call Dagger Function
        uses: dagger/dagger-for-github@v8.3.0
        with:
          version: "latest"
          module: github.com/shykes/daggerverse/hello@v0.1.2
          args: hello --greeting="bonjour" --name="monde"
          # assumes the Dagger Cloud token is in
          # a repository secret named DAGGER_CLOUD_TOKEN
          # set via the GitHub UI/CLI
          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}

You can also use Dagger shell syntax instead of Dagger call syntax in your Github Actions workflow. This is useful if you want to use the more advanced chaining and subshell capabilities of Dagger shell.

.github/workflows/dagger.yml

name: dagger
on:
  push:
    branches: [main]

jobs:
  hello:
    name: hello
    runs-on: ubuntu-latest
    steps:
      - name: Call Dagger Function
        uses: dagger/dagger-for-github@v8.3.0
        with:
          version: "latest"
          # assumes the Dagger Cloud token is in
          # a repository secret named DAGGER_CLOUD_TOKEN
          # set via the GitHub UI/CLI
          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}
      - name: Chain in dagger shell
        run: container | from alpine | file /etc/os-release | contents
        shell: dagger {0}

The following is a more complex example demonstrating how to create a GitHub Actions workflow that checks out source code, calls a Dagger Function to test the project, and then calls another Dagger Function to build and publish a container image of the project. This example uses a simple Go application and assumes that you have already forked it in your own GitHub repository.

.github/workflows/dagger.yml

name: dagger
on:
  push:
    branches: [main]

jobs:
  test:
    name: test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Test
        uses: dagger/dagger-for-github@v8.3.0
        with:
          version: "latest"
          verb: call
          module: github.com/kpenfound/dagger-modules/golang@v0.2.0
          args: test --source=.
          # assumes the Dagger Cloud token is in
          # a repository secret named DAGGER_CLOUD_TOKEN
          # set via the GitHub UI/CLI
          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}
  build:
    name: build
    runs-on: ubuntu-latest
    needs: test
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Call Dagger Function
        uses: dagger/dagger-for-github@v8.3.0
        with:
          version: "latest"
          verb: call
          module: github.com/kpenfound/dagger-modules/golang@v0.2.0
          args: build-container --source=. --args=. publish --address=ttl.sh/my-app-$RANDOM
          # assumes the Dagger Cloud token is in
          # a repository secret named DAGGER_CLOUD_TOKEN
          # set via the GitHub UI/CLI
          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}

More information is available in the Dagger for GitHub page.

Dagger Cloud Engines

Instead of spinning up a Dagger Engine inside the GitHub Actions runner, you can offload execution to a managed Dagger Engine provided by Dagger Cloud. This gives you persistent caching and additional compute capacity without provisioning your own infrastructure.

To use a Dagger Cloud Engine from a GitHub Actions workflow:

1. In Dagger Cloud, navigate to the settings page using the cogwheel icon in the top navigation bar and open the Tokens sub-menu (the same location as the Telemetry token). Copy the Compute Token. You can also use this URL pattern: https://dagger.cloud/{Your Org Name}/settings?tab=Tokens.

2. In your GitHub repository, go to Settings > Secrets and variables > Actions and click New repository secret. Name it DAGGER_CLOUD_TOKEN and paste the Compute Token as the value.

3. In your workflow, set dagger-flags: "--cloud" on the dagger/dagger-for-github step. The Dagger CLI will then connect to a Dagger Engine provided by Dagger Cloud instead of starting one inside the runner.

.github/workflows/dagger.yml

name: dagger
on:
  push:
    branches: [main]

jobs:
  hello:
    name: hello
    runs-on: ubuntu-latest
    steps:
      - name: Call Dagger Function
        uses: dagger/dagger-for-github@v8.3.0
        with:
          version: "latest"
          module: github.com/shykes/daggerverse/hello@v0.1.2
          args: hello --greeting="bonjour" --name="monde"
          # use a Dagger Engine provided by Dagger Cloud
          # instead of spinning one up inside the runner
          dagger-flags: "--cloud"
          # assumes the Dagger Cloud Compute Token is in
          # a repository secret named DAGGER_CLOUD_TOKEN
          # set via the GitHub UI/CLI
          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}

SSH configuration

When using SSH keys in GitHub Actions, ensure proper SSH agent setup:

- name: Set up SSH
  run: |
    eval "$(ssh-agent -s)"
    ssh-add - <<< '${{ secrets.SSH_PRIVATE_KEY }}'

Replace ${{ secrets.SSH_PRIVATE_KEY }} with your provider secret containing the private key.

Resources

If you have any questions about additional ways to use GitHub with Dagger, join our Discord and ask your questions in our GitHub channel.

About GitHub

GitHub is a popular Web-based platform used for version control and collaboration. It allows developers to store and manage their code in repositories, track changes over time, and collaborate with other developers on projects.