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
1

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.
2

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
3

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"
4

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"
5

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
6

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
7

Create GitHub App

Navigate to your Digger hostname to create the GitHub App:
  1. Go to https://your-digger-hostname/github/setup
  2. Follow the web interface to create your GitHub App
  3. The page will display your app credentials Digger GitHub App Setup Success
Don’t close this tab yet! You’ll need these credentials in the next steps.
8

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
9

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
10

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.
11

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
12

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:
13

Verify installation

Test that your Digger installation is working correctly:
  1. Create a test pull request in one of your repositories with Terraform/OpenTofu files
  2. Digger will automatically start planning - You should immediately see:
GitHub status checks appearing as pending:GitHub Checks PendingDigger 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