Kubernetes via Helm

Prerequisites

You have extensive understanding of Kubernetes
Installed Helm package manager version v3.11.3 or greater
You have kubectl installed and connected to your kubernetes cluster
A domain name for ingress configuration
A GitHub organization where you’ll install the GitHub App

Create Helm values

Create a values.yaml file. This will be used to configure settings for the Digger Helm chart. To explore all configurable properties for your values file, visit the values.yaml reference.

Select Digger version

By default, the Digger version set in your helm chart will likely be outdated. Choose the latest Digger docker image tag from the releases page.

values.yaml

digger:
  image:
    repository: registry.digger.dev/diggerhq/digger_backend
    tag: "v0.6.110" # Select tag from GitHub releases
    pullPolicy: IfNotPresent

Do not use the latest docker image tag in production deployments as they can introduce unexpected changes

Configure database

Choose your database configuration based on your environment:

For production environments, use an external PostgreSQL database:

values.yaml

digger:
  postgres:
    user: "digger"
    database: "digger"
    host: "postgresql.example.com"
    password: "secure-password"
    sslmode: "require"  # or "disable"

Configure ingress

Configure ingress to route traffic to Digger (required for GitHub App setup):

values.yaml

digger:
  ingress:
    enabled: true
    host: "digger.example.com"  # Your domain
    annotations:
      # Add annotations based on your ingress controller
      # Example for nginx:
      # kubernetes.io/ingress.class: "nginx"
      # cert-manager.io/cluster-issuer: "letsencrypt-prod"

Configure initial secrets

Configure the authentication and hostname settings:

values.yaml

digger:
  secret:
    httpBasicAuthUsername: "admin"
    httpBasicAuthPassword: "<strong-password>"  # CHANGE THIS
    bearerAuthToken: "<strong-token>"          # CHANGE THIS
    hostname: "https://digger.example.com"     # Include https:// prefix!
    githubOrg: "your-github-org"               # Your GitHub organization name
    
    # GitHub App credentials - leave empty for now
    githubAppID: ""
    githubAppClientID: ""
    githubAppClientSecret: ""
    githubAppKeyFile: ""
    githubWebhookSecret: ""

Hostname configuration is different from ingress:

Ingress host: digger.example.com (no protocol)
Secret hostname: https://digger.example.com (requires https:// prefix)

For example:

If your ingress host is digger.35.232.52.175.nip.io
Your secret hostname should be https://digger.35.232.52.175.nip.io

Important:

The githubOrg must be your actual GitHub organization name where you’ll install the app
Change all default passwords and tokens

Install the Helm chart

Once you are done configuring your values.yaml file, run the command below to install Digger:

helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
  --namespace digger \
  --create-namespace \
  --values values.yaml

Wait for all pods to reach a running state:

kubectl get pods -n digger

Create GitHub App

Navigate to your Digger hostname to create the GitHub App:

Go to https://your-digger-hostname/github/setup
Follow the web interface to create your GitHub App
The page will display your app credentials

Don’t close this tab yet! You’ll need these credentials in the next steps.

Update configuration with GitHub App credentials

Add the GitHub App credentials to your values.yaml file:

values.yaml

digger:
  secret:
    # ... existing configuration ...
    githubOrg: "your-github-org"
    githubAppID: "123456"
    githubAppClientID: "Iv1.abc123def456"
    githubAppClientSecret: "github_app_client_secret"
    githubAppKeyFile: "LS0tLS1CRUdJTi..."  # base64 encoded private key
    githubWebhookSecret: "webhook_secret"

Then upgrade the Helm release:

helm upgrade digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
  --namespace digger \
  --values values.yaml

Install GitHub App

Click the installation link shown in the GitHub App creation wizard:

The link will look like: https://github.com/apps/your-digger-app-name/installations/new
Install the app in your GitHub organization
Select which repositories the app can access

Create Action Secrets with cloud credentials

In GitHub repository settings, go to Secrets and Variables - Actions. Create the following secrets:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

You can also use OIDC for AWS authentication.

Create digger.yml

This file contains Digger configuration and needs to be placed at the root level of your repository:

Assuming your terraform code is in the prod directory:

projects:
- name: production
  dir: prod

Create Github Actions workflow file

Place it at .github/workflows/digger_workflow.yml (name is important!)

name: Digger Workflow

on:
  workflow_dispatch:
    inputs:
      spec:
        required: true
      run_name:
        required: false

run-name: '${{inputs.run_name}}'

jobs:
  digger-job:
    runs-on: ubuntu-latest
    permissions:
      contents: write      # required to merge PRs
      actions: write       # required for plan persistence
      id-token: write      # required for workload-identity-federation
      pull-requests: write # required to post PR comments
      issues: read         # required to check if PR number is an issue or not
      statuses: write      # required to validate combined PR status

    steps:
      - uses: actions/checkout@v4
      - name: ${{ fromJSON(github.event.inputs.spec).job_id }}
        run: echo "job id ${{ fromJSON(github.event.inputs.spec).job_id }}"
      - uses: diggerhq/digger@vLatest
        with:
          digger-spec: ${{ inputs.spec }}
          setup-aws: true
          setup-terraform: true
          terraform-version: 1.5.5
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The workflow above uses Terraform. For other tools:

OpenTofu: Replace setup-terraform: true with setup-opentofu: true and terraform-version: 1.5.5 with opentofu-version: 1.10.3
Terragrunt: Replace setup-terraform: true with setup-terragrunt: true and terraform-version: 1.5.5 with terragrunt-version: 0.44.1

For complete examples, see:

Verify installation

Test that your Digger installation is working correctly:

Create a test pull request in one of your repositories with Terraform/OpenTofu files
Digger will automatically start planning - You should immediately see:

GitHub status checks appearing as pending: GitHub Checks Pending

Digger bot comment with affected projects table: Digger Plan Jobs Table

What you should see:

GitHub checks appear as “pending” while jobs are running
Digger bot comments with a table showing each affected project
Project status updates from “pending…” to completion status

You can re-run planning anytime by commenting digger plan on the pull request.If you don’t see these responses, check the troubleshooting section below.

Troubleshooting

Failed to validate installation_id error

If you see “Failed to validate installation_id” after GitHub App installation:

Check GitHub App credentials in your values.yaml:

digger:
  secret:
    githubAppClientID: "Iv1.abc123def456"    # Should not be empty
    githubAppClientSecret: "github_secret"    # Should not be empty

Verify environment variables are set in the pod:

# Get pod name
kubectl get pods -n digger

# Check environment variables in the pod
kubectl exec -n digger deployment/digger-backend -- printenv | grep GITHUB_APP_CLIENT

Restart the deployment to pick up new environment variables:
```
kubectl rollout restart deployment/digger-backend -n digger
```

No response after creating pull request

If Digger doesn’t respond when you create a pull request:

Check backend logs for errors:

kubectl logs -n digger deployment/digger-backend --tail=100 -f

Verify webhook deliveries in GitHub:
- Go to your GitHub App settings: https://github.com/settings/apps/your-app-name
- Click on “Advanced” tab
- Check “Recent Deliveries” for failed webhook attempts
- Look for 4xx/5xx HTTP status codes or connection timeouts
Common webhook issues:
- Ensure your hostname is accessible from GitHub
- Check that your ingress is properly configured
- Verify SSL certificates are valid

Invalid URL error when creating GitHub App

If you get an “Invalid URL” error when creating the GitHub App from manifest:

Check URL format in your values.yaml:

digger:
  ingress:
    host: "digger.example.com"        # NO https:// prefix
  secret:
    hostname: "https://digger.example.com"  # REQUIRES https:// prefix

Restart deployment after fixing URLs:

kubectl rollout restart deployment/digger-backend -n digger

Introduction

Getting Started

Digger Enterprise

Features

How To

Self-host Digger

Reference

AWS-specific

GCP-specific

Azure-specific

Troubleshooting

Kubernetes via Helm

Troubleshooting

Introduction

Getting Started

Digger Enterprise

Features

How To

Self-host Digger

Reference

AWS-specific

GCP-specific

Azure-specific

Troubleshooting

​Troubleshooting

Troubleshooting