OpenTaco

https://docs.opentaco.dev
Admin
OpenTaco is an open-source platform that helps teams run Terraform and OpenTofu safely with state...
Tokens:36,843
Snippets:512
Trust Score:6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install dependencies and start UI

Source: https://docs.opentaco.dev/ce/local-development/ui

Run these commands from the ui/ directory to install required packages and start the development server.

```bash
cd ui
pnpm install   # or npm install
pnpm dev --host --port 3030
```

--------------------------------

### Initialize Docker Compose environment

Source: https://docs.opentaco.dev/ce/contributing/setup-dev-environment

Copy environment example files and start the services using the make command.

```bash
cp self-hosting/docker-compose/orchestrator.env.example self-hosting/docker-compose/orchestrator.env
cp self-hosting/docker-compose/drift.env.example self-hosting/docker-compose/drift.env
cp self-hosting/docker-compose/sidecar.env.example self-hosting/docker-compose/sidecar.env
cp self-hosting/docker-compose/ui.env.example self-hosting/docker-compose/ui.env

# from repo root
make -C self-hosting/docker-compose all-up

# or run from the compose directory
# cd self-hosting/docker-compose
# make all-up
```

--------------------------------

### Navigate to sandbox-sidecar and install dependencies

Source: https://docs.opentaco.dev/self-hosting/e2b-setup

Prepare the environment by entering the sandbox-sidecar directory and installing required packages.

```bash
cd sandbox-sidecar
npm install
```

--------------------------------

### Start the backend service

Source: https://docs.opentaco.dev/ce/local-development/backend

Load the environment variables and start the Go application from the backend directory.

```bash
set -a; source .env; set +a
go run main.go              # or: make start
```

--------------------------------

### Initialize values file

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Copy the production or platform-reference example to create your deployment-specific values file.

```bash
cp helm-charts/opentaco/values-production.yaml.example values-opentaco.yaml
```

```bash
cp helm-charts/opentaco/values.platform-reference.yaml values-opentaco.yaml
```

--------------------------------

### Install the platform reference chart

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Deploy the platform reference chart to bootstrap supporting resources.

```bash
helm upgrade --install opentaco-platform-reference \
  oci://ghcr.io/diggerhq/helm-charts/opentaco-platform-reference \
  --version 0.1.0 \
  -n opentaco
```

--------------------------------

### Start all services with Docker Compose

Source: https://docs.opentaco.dev/ce/local-development/overview

Use the Makefile in the self-hosting directory to initialize the full stack environment.

```bash
# from repo root
make -C self-hosting/docker-compose all-up

# or run from the compose directory
# cd self-hosting/docker-compose
# make all-up
```

--------------------------------

### Copy environment configuration files

Source: https://docs.opentaco.dev/self-hosting/docker-compose

Initialize the required environment variable files by copying the provided examples.

```bash
cp self-hosting/docker-compose/orchestrator.env.example self-hosting/docker-compose/orchestrator.env
cp self-hosting/docker-compose/drift.env.example self-hosting/docker-compose/drift.env
cp self-hosting/docker-compose/sidecar.env.example self-hosting/docker-compose/sidecar.env
cp self-hosting/docker-compose/ui.env.example self-hosting/docker-compose/ui.env
```

--------------------------------

### Start Compose baseline

Source: https://docs.opentaco.dev/ce/local-development/overview

Commands to initialize the Docker Compose environment from the repository root or the specific directory.

```bash
# from repo root
make -C self-hosting/docker-compose all-up

# or from self-hosting/docker-compose
make all-up
```

--------------------------------

### Start Statesman from source

Source: https://docs.opentaco.dev/ce/local-development/statesman

Run the Statesman service directly from the source code with the necessary environment variables.

```bash
export OPENTACO_PORT=8080
export OPENTACO_ENABLE_INTERNAL_ENDPOINTS=statesman-secret
export OPENTACO_STORAGE=memory
export OPENTACO_AUTH_DISABLE=true

go run ./cmd/statesman
```

--------------------------------

### Install OpenTaco chart

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Deploy the OpenTaco umbrella chart using Helm with the specified values file.

```bash
helm upgrade --install opentaco \
  oci://ghcr.io/diggerhq/helm-charts/opentaco \
  --version 0.1.0-public \
  -f values-opentaco.yaml \
  -n opentaco
```

--------------------------------

### Define project directory structure

Source: https://docs.opentaco.dev/ce/howto/include-exclude-patterns

Example directory structure showing environment folders and a shared modules directory.

```yml
development/
  main.tf
production/
  main.tf
modules/
  shared_moduleA/
  dev_only_module/
```

--------------------------------

### Start OpenTaco services with Makefile

Source: https://docs.opentaco.dev/self-hosting/docker-compose

Use Makefile targets to launch specific service groups or the entire stack.

```bash
# start only shared platform services (databases/object storage)
make platform-up

# start only OpenTaco application services
# (only when providing external databases/object storage)
make opentaco-up

# start everything
make all-up
```

--------------------------------

### Configure Basic Terragrunt Setup

Source: https://docs.opentaco.dev/ce/reference/terragrunt-parsing

Enables Terragrunt parsing for a specific infrastructure block with automatic planning and dependency cascading.

```yaml
generate_projects:
  terragrunt: true
  blocks:
    - block_name: infrastructure
      terragrunt: true
      root_dir: infrastructure
      terragrunt_parsing:
        autoPlan: true
        cascadeDependencies: true
```

--------------------------------

### Setup Infracost Action

Source: https://docs.opentaco.dev/ce/howto/using-infracost

Configure the Infracost GitHub action in your workflow file using an API key.

```yaml
- name: Setup Infracost
        uses: infracost/actions/setup@v2
        # See https://github.com/infracost/actions/tree/master/setup for other inputs
        # If you can't use this action, see Docker images in https://infracost.io/cicd
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}
```

--------------------------------

### Digger plan command examples

Source: https://docs.opentaco.dev/ce/reference/comment-args

Various ways to invoke the digger plan command using project and directory flags.

```bash
digger plan -p dev_vpc
```

```bash
digger plan --project dev_vpc
```

```bash
digger plan -d dev/vpc
```

```bash
digger plan --directory dev/vpc
```

```bash
digger plan -p dev_vpc -p staging_vpc
```

```bash
digger plan -p dev_vpc -d staging/vpc
```

--------------------------------

### Complete Digger Configuration

Source: https://docs.opentaco.dev/ce/reference/digger.yml

A comprehensive example covering project definitions, workflow steps, environment variables, and advanced settings like drift detection and AWS role assumption.

```yaml
traverse_to_nested_projects: true
auto_merge: false
pr_locks: true
allow_draft_prs: false
apply_after_merge: false
comment_render_mode: basic
report_terraform_outputs: true
mention_drifted_projects_in_pr: false
disable_digger_apply_comment: false
disable_digger_apply_status_check: false
trusted_appIDs:
  - 41898282
respect_layers: false
reporting:
  ai_summary: false
  comments_enabled: true
dependency_configuration:
  mode: hard
projects:
  - name: prod
    dir: prod
    alias: production
    apply_requirements: [approved, mergeable, undiverged]
    branch: main
    workspace: default
    terragrunt: false
    opentofu: false
    pulumi: false
    pulumi_stack: ""
    workflow: prod
    workflow_file: digger_workflow.yml
    drift_detection: true
    layer: 0
    include_patterns: ["../modules/**"]
    exclude_patterns: []
    depends_on: []
    aws_role_to_assume:
      aws_role_region: us-east-1
      state: arn:aws:iam::123456789012:role/state-role
      command: arn:aws:iam::123456789012:role/command-role
    aws_cognito_oidc:
      aws_account_id: "123456789012"
      aws_region: us-east-1
      cognito_identity_pool_id: us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      session_duration: 3600
  - name: staging
    dir: staging
    branch: main
    workflow: staging
    include_patterns: ["../modules/**"]
    exclude_patterns: []
generate_projects:
  include: "../projects/**"
  exclude: "../.terraform/**"
  terragrunt: false
  blocks:
    - block_name: dev-block
      include: "dev/**"
      exclude: "dev/.terraform/**"
      workflow: dev
      workflow_file: digger_workflow.yml
      opentofu: false
      terragrunt: false
      include_patterns: []
      exclude_patterns: []
      aws_role_to_assume:
        aws_role_region: us-east-1
        state: arn:aws:iam::123456789012:role/state-role
        command: arn:aws:iam::123456789012:role/command-role
workflows:
  staging:
    env_vars:
      state:
        - name: TF_LOG
          value: trace
      commands:
        - name: TF_LOG
          value: trace
    plan:
      filter_regex: ""
      steps:
        - init:
          extra_args: ["backend-config=../backend.hcl"]
        - run: "echo hello world"
        - plan
    apply:
      filter_regex: ""
      steps:
        - run: "echo hello world"
          shell: zsh
        - init
        - apply:
          extra_args: ["-compact-warnings"]
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_pull_request_to_draft: []
      on_commit_to_default: ["digger apply"]
      skip_merge_check: false
  prod:
    env_vars:
      state:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_BACKEND_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_BACKEND_TF_SECRET__ACCESS_KEY
      commands:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_TF_SECRET_ACCESS_KEY
    plan:
      steps:
        - run: "checkov -d ."
        - init
        - plan
    apply:
      steps:
        - run: "terraform fmt -check -diff -recursive"
          shell: zsh
        - init
        - apply
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_commit_to_default: ["digger unlock"]
```

--------------------------------

### Configure Digger Workflow

Source: https://docs.opentaco.dev/ce/gcp/federated-oidc-access

Example GitHub Actions workflow configuration for authenticating with GCP via OIDC and running Digger.

```yaml
- id: 'auth'
        uses: 'google-github-actions/auth@v1'
        with:
          token_format: access_token
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ env.GCP_SERVICE_ACCOUNT }}
          audience: google-wif

      - name: 'Set up Cloud SDK'
        uses: 'google-github-actions/setup-gcloud@v1'

      - name: 'Use gcloud CLI'
        run: |
          gcloud info
          gsutil ls gs://${{ env.GOOGLE_STORAGE_BUCKET }}
      - name: digger
        uses: diggerhq/digger@vLatest
        env:
          LOCK_PROVIDER: gcp
          GITHUB_CONTEXT: ${{ toJson(github) }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GOOGLE_STORAGE_BUCKET: digger-lock2
```

--------------------------------

### Define CODEOWNERS file

Source: https://docs.opentaco.dev/ce/howto/codeowners

Example configuration for a CODEOWNERS file to assign specific reviewers to production changes.

```text
prod @ZIJ # ensure ZIJ is reviewer for any prod changes
```

--------------------------------

### Define RBAC Permission Rules

Source: https://docs.opentaco.dev/ce/state-management/rbac

Examples of permission rule strings using the effect:actions:resources format.

```bash
# Allow read/write access to all dev environments
allow:unit.read,unit.write:dev/*

# Allow full access to specific production unit
allow:unit.read,unit.write,unit.lock,unit.delete:myapp/prod

# Deny deletion of production units
deny:unit.delete:myapp/prod

# Allow RBAC management
allow:rbac.manage:*
```

--------------------------------

### Configure Multi-environment Terragrunt Setup

Source: https://docs.opentaco.dev/ce/reference/terragrunt-parsing

Defines global Terragrunt parsing behavior including workflow defaults and project preservation settings.

```yaml
generate_projects:
  terragrunt: true
  terragrunt_parsing:
    autoPlan: true
    autoMerge: false
    createParentProject: false
    ignoreDependencyBlocks: false
    cascadeDependencies: true
    defaultApplyRequirements: ["approved", "mergeable"]
    defaultWorkflow: terragrunt-workflow
    preserveProjects: true
```

--------------------------------

### Configure environment variables for multi-cloud setup

Source: https://docs.opentaco.dev/ce/howto/segregate-cloud-accounts

Define secrets in your CI/CD environment to handle authentication for Digger locks, Terraform state, and Azure infrastructure.

```yaml
env:
   DIGGER_AWS_ACCESS_KEY_ID: ${{secrets.DIGGER_AWS_ACCESS_KEY_ID}}
   DIGGER_AWS_SECRET_ACCESS_KEY: ${{secrets.DIGGER_AWS_SECRET_ACCESS_KEY}}
   STATE_ACCESS_KEY_ID: ${{secrets.STATE_AWS_KEY_ID}}
   STATE_SECRET_ACCESS_KEY: ${{secrets.STATE_SECRET_ACCESS_KEY}}
   DEV_ARM_MSI_ENDPOINT: ${{secrets.DEV_ARM_MSI_ENDPOINT}}
   DEV_ARM_SUBSCRIPTION_ID: ${{secrets.DEV_ARM_SUBSCRIPTION_ID}}
   DEV_ARM_TENANT_ID: ${{secrets.ARM_TENANT_ID}}
   DEV_ARM_USE_MSI: ${{secrets.ARM_USE_MSI}}
```

--------------------------------

### Stop UI container for hybrid workflow

Source: https://docs.opentaco.dev/ce/local-development/ui

Use these commands to start the core services in Docker while stopping the UI container to allow local development.

```bash
make -C self-hosting/docker-compose all-up
docker compose -f self-hosting/docker-compose/docker-compose.yml stop ui
```

--------------------------------

### Configure dynamic Terragrunt project generation

Source: https://docs.opentaco.dev/ce/howto/using-terragrunt

Enable automatic project discovery and dependency handling for large Terragrunt setups.

```yaml
generate_projects:
  terragrunt_parsing:
    parallel: true
    createProjectName: true
    createWorkspace: true
    defaultWorkflow: default
workflows:
  default:
    plan:
      steps:
        - init
        - plan
        - run: echo "Terragrunt generation!"
```

--------------------------------

### Configure IaC tool installation

Source: https://docs.opentaco.dev/onboarding/configuring-github-actions-workflow

Specify the IaC tool and version to be used by the Digger action. Choose between OpenTofu, Terraform, or Terragrunt configurations.

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-opentofu: true
    opentofu-version: 1.10.3
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-terraform: true
    terraform-version: 1.5.5
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-terragrunt: true
    terragrunt-version: 0.44.1
    # Also install one IaC engine with Terragrunt.
    # OpenTofu is the default recommendation:
    setup-opentofu: true
    opentofu-version: 1.10.3
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Configure patterns relative to project directory

Source: https://docs.opentaco.dev/ce/howto/include-exclude-patterns

Uses patterns starting with '.' to resolve paths relative to the project directory defined in the 'dir' key.

```yml
projects:
  - name: dev
    dir: ./development
    include_patterns: ["../modules/**"]  # Resolved from ./development/
    workflow: default_workflow
  - name: prod
    dir: ./production
    include_patterns: ["../modules/**"]  # Resolved from ./production/
    exclude_patterns: ["../modules/dev_only_module/**"]
```

--------------------------------

### Digger action configuration inputs

Source: https://docs.opentaco.dev/ce/reference/action-inputs

A comprehensive list of all available inputs for the Digger action, including cloud provider setup, tool versions, and reporting configurations.

```yaml
inputs:
  setup-aws:
    description: Setup AWS
    required: false
    default: 'false'
  aws-access-key-id:
    description: AWS access key id
    required: false
  aws-secret-access-key:
    description: AWS secret access key
    required: false
  aws-role-to-assume:
    description: ARN of AWS IAM role to assume using OIDC
    required: false
  aws-region:
    description: AWS region
    required: false
    default: us-east-1
  setup-google-cloud:
    description: Setup google cloud
    required: false
    default: 'false'
  google-auth-credentials:
      description: Service account key used got Google auth (mutually exclusive with 'google-workload-identity-provider' input)
      required: false
  google-workload-identity-provider:
      description: Workload identity provider to be used for Google OIDC auth (mutually exclusive with 'google-auth-credentials' input)
      required: false
  google-workload-identity-provider-audience:
      description: "'audience' parameter configured in Google's Workload Identity Provider (if specified). To be used when the 'google-workload-identity-provider' input is specified"
      required: false
  google-service-account:
    description: Service account to be used when the 'google-workload-identity-provider' input is specified)
    required: false
  google-lock-bucket:
    description: The GCP bucket to use for PR locks in backendless mode (`no-backend: true`)
    required: false
  setup-azure:
    description: Setup Azure
    required: false
    default: 'false'
  azure-client-id:
    description: Azure Client ID to be used for Azure OIDC auth
    required: false
  azure-tenant-id:
    description: AzureAD ID of the organization you are using
    required: false
  azure-subscription-id:
    description: Subscription ID of you are using
    required: false
  setup-terragrunt:
    description: Setup terragrunt
    required: false
    default: 'false'
  setup-opentofu:
    description: Setup OpenToFu
    required: false
    default: 'false'
  terragrunt-version:
    description: Terragrunt version
    required: false
    default: v0.55.5
  opentofu-version:
    description: OpenTofu version
    required: false
    default: v1.6.1
  setup-terraform:
    description: Setup terraform
    required: false
    default: 'false'
  terraform-version:
    description: Terraform version
    required: false
    default: v1.5.5
  configure-checkout:
    description: Configure checkout. Beware that this will overwrite any changes in the working directory
    required: false
    default: 'true'
  upload-plan-destination:
    description: Destination to upload the plan to. azure, gcp, github and aws are currently supported.
    required: false
  upload-plan-destination-s3-bucket:
    description: Name of the destination bucket for AWS S3. Should be provided if destination == aws
    required: false
  upload-plan-destination-azure-container:
    description: Name of the destination storage account container for Azure blob storage. Should be provided if destination == azure
    required: false
  upload-plan-destination-azure-storage-account:
    description: Name of the destination storage account for Azure blob storage. Should be provided if destination == azure
    required: false
  upload-plan-destination-gcp-bucket:
    description: Name of the destination bucket for a GCP bucket. Should be provided if destination == gcp
    required: false
  setup-checkov:
    description: Setup Checkov
    required: false
    default: 'false'
  checkov-version:
    description: Checkov version
    required: false
    default: '3.2.22'
  disable-locking:
    description: Disable locking (deprecated, use pr_locks on digger.yml instead)
    required: false
    default: 'false'
  digger-filename:
    description: Alternative Digger configuration file name
    required: false
  digger-token:
    description: Digger token
    required: false
  digger-hostname:
    description: Digger hostname
    required: false
    default: 'https://cloud.digger.dev'
  digger-organisation:
    description: The name of your digger organisation
    required: false
  setup-tfenv:
    description: Setup tfenv
    required: false
    default: 'false'
  post-plans-as-one-comment:
    description: Post plans as one comment
    required: false
    default: 'false'
  reporting-strategy:
    description: 'comments_per_run or latest_run_comment, anything else will default to original behavior of multiple comments'
    required: false
    default: 'comments_per_run'
  mode:
    description: 'manual, drift-detection or otherwise'
    required: false
    default: ''
  no-backend:
    description: 'run cli-only, without an orchestrator backend'
    required: false
    default: 'false'
```

--------------------------------

### Example Terraform output

Source: https://docs.opentaco.dev/ce/howto/masking-sensitive-values

An example of a Terraform output block that would be affected by the configured masking regex.

```hcl
output "filterme" {
  value = "example_secret: filterme: topsecret"
}
```

--------------------------------

### GET /orgs/:organisation/access-policy

Source: https://docs.opentaco.dev/ce/reference/api

Retrieves the access policy rules for an entire organisation.

```APIDOC
## GET /orgs/:organisation/access-policy

### Description
Retrieves the access policy rules for an entire organisation.

### Method
GET

### Endpoint
/orgs/:organisation/access-policy

### Parameters
#### Path Parameters
- **organisation** (string) - Required - The name of the organisation.
```

--------------------------------

### GET /repos/:namespace/projects/:projectName/access-policy

Source: https://docs.opentaco.dev/ce/reference/api

Retrieves the access policy rules for a specific project.

```APIDOC
## GET /repos/:namespace/projects/:projectName/access-policy

### Description
Retrieves the access policy rules for a specific project.

### Method
GET

### Endpoint
/repos/:namespace/projects/:projectName/access-policy

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The repository namespace.
- **projectName** (string) - Required - The name of the project.
```

--------------------------------

### Configure backend environment variables

Source: https://docs.opentaco.dev/ce/local-development/backend

Create a .env file in the backend directory with these essential configuration settings.

```bash
DATABASE_URL=postgres://postgres:postgres-password-CHANGE_ME@localhost:5432/orchestrator?sslmode=disable
DIGGER_INTERNAL_SECRET=orchestrator-secret          # must match UI ORCHESTRATOR_BACKEND_SECRET
DIGGER_ENABLE_INTERNAL_ENDPOINTS=true               # enables /_internal/*
DIGGER_ENABLE_API_ENDPOINTS=true                    # enables /api/*
PUBLIC_BASE_URL=http://localhost:3000               # public URL used for GitHub app callbacks
INTERNAL_BASE_URL=http://localhost:3000             # internal backend URL
```

--------------------------------

### Initialize Terraform project

Source: https://docs.opentaco.dev/onboarding/state-management

Run the initialization command to verify the connection to the OpenTaco backend.

```bash
➜  ~ terraform init

Initializing Terraform Cloud...

Initializing provider plugins...

Terraform Cloud has been successfully initialized!

You may now begin working with Terraform Cloud. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.
```

--------------------------------

### Validate job event JSON structure

Source: https://docs.opentaco.dev/ce/troubleshooting/action-errors

Example of a valid JSON structure for the job event input.

```json
   "event": {
      "inputs": {
        "comment_id": "2083250779",
        "id": "EiUBxZHh0qXQ92PR",
        "job": "{\"projectName\":\"dev\",\"projectDir\":\".\",\"projectWorkspace\":\"default\",\"terragrunt\":false,\"commands\":[\"digger plan\"],\"applyStage\":{\"steps\":[{\"action\":\"init\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"},{\"action\":\"apply\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"}]},\"planStage\":{\"steps\":[{\"action\":\"init\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"},{\"action\":\"plan\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"}]},\"pullRequestNumber\":9,\"eventName\":\"issue_comment\",\"requestedBy\":\"motatoes\",\"namespace\":\"diggerhq/demo-opentofu\",\"runEnvVars\":{\"DEFAULT_BRANCH\":\"main\",\"PROJECT_DIR\":\".\",\"PROJECT_NAME\":\"dev\",\"PR_BRANCH\":\"motatoes-patch-7\"},\"stateEnvVars\":{},\"commandEnvVars\":{},\"state_role_name\":\"\",\"command_role_name\":\"\",\"backend_hostname\":\"https://c1db-5-151-139-93.ngrok-free.app\",\"backend_organisation_hostname\":\"digger\",\"backend_job_token\":\"cli:f4bfd7a5-ec11-4d43-ab88-93d12674e1d7\"}"
      },
```

--------------------------------

### Create Service Account and Bind Policies

Source: https://docs.opentaco.dev/ce/gcp/federated-oidc-access

Creates a service account and grants the necessary IAM roles for WIF impersonation.

```bash
gcloud iam service-accounts create test-wif \
--display-name="Service account used by WIF POC" \
--project

gcloud projects add-iam-policy-binding  \
--member='serviceAccount:test-wif@.iam.gserviceaccount.com' \
--role="roles/compute.viewer"
gcloud iam service-accounts add-iam-policy-binding test-wif@.iam.gserviceaccount.com \
--project= \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/github-wif-pool/attribute.repository/PradeepSingh1988/gcp-wif"
```

--------------------------------

### Create Kubernetes namespaces

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Initialize the required namespaces for OpenTaco and Traefik.

```bash
kubectl create namespace opentaco
kubectl create namespace traefik
```

--------------------------------

### Example Digger lock comment

Source: https://docs.opentaco.dev/ce/azure-specific/azure

The expected output comment in a pull request when a project is successfully locked.

```text
Project diggerhq/azure-onboarding-test#infra-prod has been locked by PR #1
```

--------------------------------

### Configure UI environment variables

Source: https://docs.opentaco.dev/ce/local-development/ui

Copy these settings into .env.local within the ui/ directory to configure authentication, backend URLs, and secrets.

```bash
# URLs
PUBLIC_URL=http://localhost:3030                            # replace with ngrok URL when exposing UI
ALLOWED_HOSTS=localhost,127.0.0.1                           # include ngrok hostname when exposing UI

# WorkOS (User Management)
WORKOS_CLIENT_ID=<your_workos_client_id>
WORKOS_API_KEY=<your_workos_api_key>
WORKOS_COOKIE_PASSWORD=<32+ random chars>
WORKOS_REDIRECT_URI=http://localhost:3030/api/auth/callback # replace with ngrok callback URL; must match WorkOS config
WORKOS_WEBHOOK_SECRET=<if using webhooks locally via tunnel>

# Backend
ORCHESTRATOR_BACKEND_URL=http://localhost:3000
ORCHESTRATOR_BACKEND_SECRET=orchestrator-secret   # matches backend DIGGER_INTERNAL_SECRET
ORCHESTRATOR_GITHUB_APP_URL=http://localhost:3000/github/setup  # or your app install URL

# Statesman
STATESMAN_BACKEND_URL=http://localhost:8080
STATESMAN_BACKEND_WEBHOOK_SECRET=statesman-secret  # matches OPENTACO_ENABLE_INTERNAL_ENDPOINTS

# Optional
DRIFT_REPORTING_BACKEND_URL=http://localhost:3001
DRIFT_REPORTING_BACKEND_WEBHOOK_SECRET=...
POSTHOG_KEY=...
```

--------------------------------

### Build and publish templates

Source: https://docs.opentaco.dev/self-hosting/e2b-setup

Execute the build scripts to compile and publish sandbox templates to E2B.

```bash
npx tsx templates/build-all.ts
```

```bash
npx tsx templates/build-barebones.ts
```

--------------------------------

### Terraform Initialization and Execution Plan

Source: https://docs.opentaco.dev/onboarding/remote-jobs

Displays the output of a successful Terraform initialization and the subsequent execution plan for a null_resource.

```hcl
Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/null from the dependency lock file
- Installing hashicorp/null v3.2.4...
- Installed hashicorp/null v3.2.4 (signed by HashiCorp)

Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Terraform has been successfully initialized!

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # null_resource.smoke_test will be created
  + resource "null_resource" "smoke_test" {
      + id = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Plan complete
```

--------------------------------

### Terraform resource already exists error

Source: https://docs.opentaco.dev/ce/troubleshooting/importing-existing-resources

Example of the error message encountered when a resource already exists in the registry.

```text
Error: creating ECR Repository (xxx): 
RepositoryAlreadyExistsException: The repository with name 'xxx' already exists in the 
registry with id ...
```

--------------------------------

### Authenticate with CLI

Source: https://docs.opentaco.dev/onboarding/state-management

Run the login command to authenticate your local environment with the OpenTaco host.

```bash
terraform login otaco.app
```

--------------------------------

### Validate platform reference resources

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Check the status of pods and verify the rollout of critical services.

```bash
kubectl get pods -n opentaco
kubectl get pods -n traefik
kubectl rollout status deployment/cloudnative-pg -n opentaco --timeout=180s
kubectl rollout status statefulset/minio -n opentaco --timeout=300s
```

--------------------------------

### Define basic Terraform steps

Source: https://docs.opentaco.dev/ce/reference/digger.yml

Use a simple list of strings to execute standard Terraform commands in sequence.

```yaml
steps:
  - init
  - plan
  - apply
```

--------------------------------

### Define a default Digger workflow

Source: https://docs.opentaco.dev/ce/reference/digger.yml

Example of a basic workflow configuration that executes commands based on pull request and commit events.

```yaml
workflow_configuration:
  on_pull_request_pushed: [digger plan]
  on_pull_request_closed: [digger unlock]
  on_commit_to_default: [digger unlock]
plan:
  steps:
    - init
    - plan
apply:
  steps:
    - init
    - apply
```

--------------------------------

### List Roles and Permissions

Source: https://docs.opentaco.dev/ce/state-management/rbac

Displays all roles and their currently assigned permissions.

```bash
# View all roles and their assigned permissions
taco rbac role list
```

--------------------------------

### Set up Terragrunt in GitHub Actions

Source: https://docs.opentaco.dev/ce/howto/using-terragrunt

Include the setup-terragrunt flag in the Digger workflow to enable Terragrunt support.

```yaml
name: Digger

on:
  workflow_dispatch:

jobs:
  digger-job:
    runs-on: ubuntu-latest
    steps:
      - uses: diggerhq/digger@vLatest
        with:
          setup-terragrunt: true
          terragrunt-version: 0.44.1
```

--------------------------------

### Manage service lifecycle with Makefile

Source: https://docs.opentaco.dev/self-hosting/docker-compose

Common commands for monitoring, restarting, and cleaning up the Docker Compose stack.

```bash
make ps

# stream service logs
make logs

# restart services
make restart

# stop and remove services
make down

# rebuild images and start services
make up-build

# recreate services without rebuilding images
make recreate

# rebuild images and force recreate services
make rebuild
```

--------------------------------

### Execute RBAC Workflow

Source: https://docs.opentaco.dev/ce/state-management/rbac

A complete CLI sequence to initialize RBAC, define permissions, assign them to roles, and map roles to users.

```bash
# 1. Initialize RBAC
taco rbac init

# 2. Create permissions
taco rbac permission create dev-access "Developer Access" "Access to dev environments" \
  --rule "allow:unit.read,unit.write,unit.lock:dev/*"

taco rbac permission create prod-read "Production Read" "Read-only access to production" \
  --rule "allow:unit.read:myapp/prod"

# 3. List permissions to verify
taco rbac permission list

# 4. Create roles
taco rbac role create developer "Developer" "Can access dev environments"
taco rbac role create viewer "Viewer" "Can view production states"

# 5. Assign permissions to roles
taco rbac role assign-permission developer dev-access
taco rbac role assign-permission viewer prod-read

# 6. List roles to verify permissions are assigned
taco rbac role list

# 7. Assign roles to users
taco rbac user assign john.doe@example.com developer
taco rbac user assign jane.smith@example.com viewer

# 8. Test permissions
taco rbac test john.doe@example.com lock dev/myapp
taco rbac test john.doe@example.com lock myapp/prod
taco rbac test jane.smith@example.com read myapp/prod
taco rbac test jane.smith@example.com write myapp/prod
```

--------------------------------

### Create a minimal OpenTofu smoke test

Source: https://docs.opentaco.dev/onboarding/configure-pr-automation-workflows

Define a basic null resource in a main.tf file to verify the automation pipeline without requiring state management.

```hcl
resource "null_resource" "smoke_test" {}
```

--------------------------------

### Configure apply requirements for production projects

Source: https://docs.opentaco.dev/ce/security/overview

Use this configuration to enforce mergeability, approval, and branch synchronization for production environments.

```yaml
projects:
  - name: prod
    dir: prod
    apply_requirements: [mergeable, approved, undiverged]
```

--------------------------------

### Create Roles

Source: https://docs.opentaco.dev/ce/state-management/rbac

Creates empty roles to which permissions can later be assigned.

```bash
# Create roles (initially with no permissions)
taco rbac role create developer "Developer" "Can access dev environments"
taco rbac role create viewer "Viewer" "Can view production units"
taco rbac role create admin "Administrator" "Full system access"
```

--------------------------------

### Configure OpenTofu projects

Source: https://docs.opentaco.dev/onboarding/configuring-digger-yml

Define OpenTofu projects explicitly or via generation patterns.

```yaml
projects:
- name: core
  dir: infra/core
  opentofu: true
- name: app
  dir: infra/app
  opentofu: true
```

```yaml
generate_projects:
  include: "infra/**"
  terragrunt: false
  opentofu: true
```

--------------------------------

### Initialize RBAC

Source: https://docs.opentaco.dev/ce/state-management/rbac

Initializes the RBAC system and assigns default roles to the current user.

```bash
# Login first
taco login

# Initialize RBAC for your user
taco rbac init
```

--------------------------------

### Basic Digger Configuration

Source: https://docs.opentaco.dev/ce/reference/digger.yml

Define multiple projects and enable auto-merge in the root digger.yml file.

```yaml
projects:
  - name: my-first-app
    dir: app-one
  - name: my-second-app
    dir: app-two
auto_merge: true
```

--------------------------------

### Expose UI via ngrok

Source: https://docs.opentaco.dev/ce/local-development/ui

Use ngrok to expose the local UI port to the internet for testing webhooks and external callbacks.

```bash
ngrok http 3030
```

--------------------------------

### Create Permissions

Source: https://docs.opentaco.dev/ce/state-management/rbac

Defines specific access rules for resources using allow effects.

```bash
# Create a permission for developer access to dev environments
taco rbac permission create dev-access "Developer Access" "Access to dev environments" \
  --rule "allow:unit.read,unit.write,unit.lock:dev/*"

# Create a permission for production read-only access
taco rbac permission create prod-read "Production Read" "Read-only access to production" \
  --rule "allow:unit.read:myapp/prod"

# Create a permission for admin full access
taco rbac permission create admin-full "Admin Full Access" "Full system access" \
  --rule "allow:unit.read,unit.write,unit.lock,unit.delete:*" \
  --rule "allow:rbac.manage:*"
```

--------------------------------

### Basic generate_projects configuration

Source: https://docs.opentaco.dev/ce/howto/generate-projects

Use this configuration to define a simple inclusion and exclusion pattern for project generation.

```yaml
generate_projects:
  include: "projects/dev/*"
  exclude: "projects/dev/test3"
```

--------------------------------

### Build CLI binary

Source: https://docs.opentaco.dev/ce/contributing/setup-dev-environment

Compile the Digger CLI binary from the source code for local testing.

```bash
cd cli
go build -o digger ./cmd/digger
chmod +x digger
```

--------------------------------

### Define custom shell command steps

Source: https://docs.opentaco.dev/ce/reference/digger.yml

Use the run key to execute shell commands, optionally specifying the shell interpreter.

```yaml
steps:
  - run: "echo hello world"
  - run: "checkov -d ."
    shell: zsh
```

--------------------------------

### Sync organization and user for UI flows

Source: https://docs.opentaco.dev/ce/local-development/backend

Use these curl commands to upsert the organization and user data required for UI authentication.

```bash
SECRET=$DIGGER_INTERNAL_SECRET
ORG_ID=org_xxx                           # WorkOS org id
ORG_NAME=my-org                          # slug shown in backend
ADMIN_EMAIL=you@example.com
USER_ID=user_xxx                         # WorkOS user id
USER_EMAIL=$ADMIN_EMAIL

# org
curl -s -X POST http://localhost:3000/_internal/api/upsert_org \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"org_name":"'"$ORG_NAME"'","external_source":"workos","external_id":"'"$ORG_ID"'","admin_email":"'"$ADMIN_EMAIL"'"}'

# user
curl -s -X POST http://localhost:3000/_internal/api/create_user \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"external_source":"workos","external_id":"'"$USER_ID"'","email":"'"$USER_EMAIL"'","external_org_id":"'"$ORG_ID"'"}'
```

--------------------------------

### Configure GitHub Actions for Drift Issues

Source: https://docs.opentaco.dev/ce/drift/github-issues

Add these environment variables to your drift workflow to enable GitHub Issue creation. Ensure the provided token has sufficient repository permissions.

```yml
env:
  GITHUB_CONTEXT: ${{ toJson(github) }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  INPUT_DRIFT_GITHUB_ISSUES: 'true'
  # Optional: DIGGER_GITHUB_TOKEN or PAT with appropriate scopes
```

--------------------------------

### Specify Terraform version in workflow

Source: https://docs.opentaco.dev/ce/howto/specify-terraform-version

Configure the Terraform version by setting setup-terraform to true and specifying the desired version string.

```yaml
jobs:
  destroy:
    runs-on: ubuntu-latest
    steps:
    - name: digger destroy
      uses: diggerhq/digger@vLatest
      with:
        setup-terraform: true
        terraform-version: v1.5.5
      env:
        GITHUB_CONTEXT: ${{ toJson(github) }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Specify OpenTofu version in workflow

Source: https://docs.opentaco.dev/ce/howto/specify-terraform-version

Configure the OpenTofu version by setting setup-opentofu to true and specifying the desired version string. Ensure opentofu is enabled in the project settings in digger.yml.

```yaml
jobs:
  destroy:
    runs-on: ubuntu-latest
    steps:
    - name: digger destroy
      uses: diggerhq/digger@vLatest
      with:
        setup-opentofu: true
        opentofu-version: v1.6.1
      env:
        GITHUB_CONTEXT: ${{ toJson(github) }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Define explicit projects for drift detection

Source: https://docs.opentaco.dev/ce/drift/backendless-scoping-projects

Create a dedicated configuration file listing specific projects to be scanned.

```yml
# digger-drift-dev.yml
projects:
  - name: app-dev-a
    dir: terraform/aws_devel/app-a
    workflow: default
  - name: app-dev-b
    dir: terraform/aws_devel/app-b
    workflow: default
```

--------------------------------

### Configure GitHub Actions for local CLI

Source: https://docs.opentaco.dev/ce/contributing/setup-dev-environment

Set the required action inputs in your workflow step to use the locally built CLI.

```yaml
local-dev-mode: "true"
local-dev-cli-path: "/absolute/path/to/cli"
```

--------------------------------

### Configure GitHub Actions workflow

Source: https://docs.opentaco.dev/ce/azure-specific/azure

Define the CI workflow in .github/workflows/infra.yml to execute Digger with Azure credentials.

```yaml
name: CI

on:
  pull_request:
    branches: [ "main" ]
    types: [ closed, opened, synchronize, reopened ]
  issue_comment:
    types: [created]
    if: contains(github.event.comment.body, 'digger')
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Checkout Pull Request
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_URL="${{ github.event.issue.pull_request.url }}"
          PR_NUM=${PR_URL}
          echo "Checking out from PR #$PR_NUM based on URL: $PR_URL"
          hub pr checkout $PR_NUM
        if: github.event_name == 'issue_comment'

      - name: digger
        uses: diggerhq/digger@vLatest
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LOCK_PROVIDER: azure
          DIGGER_AZURE_AUTH_METHOD: CONNECTION_STRING
          DIGGER_AZURE_CONNECTION_STRING: ${{ secrets.DIGGER_AZURE_CONNECTION_STRING }}
          ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }}
          ARM_CLIENT_SECRET: ${{ secrets.ARM_CLIENT_SECRET }}
          ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }}
          ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }}
```

--------------------------------

### Create Kubernetes secrets from environment files

Source: https://docs.opentaco.dev/ce/security/overview

Use this command to generate a Kubernetes secret from an environment file and apply it to the cluster.

```bash
kubectl create secret generic ui-secrets \
  --from-env-file=helm-charts/secrets-example/ui.env \
  -n opentaco --dry-run=client -o yaml | kubectl apply -f -
```

--------------------------------

### Configure digger.yml

Source: https://docs.opentaco.dev/onboarding/configure-pr-automation-workflows

Define the project structure and enable OpenTofu integration in the root directory.

```yaml
projects:
  - name: production
    dir: smoke-test
    opentofu: true
```

--------------------------------

### Define Digger project configuration

Source: https://docs.opentaco.dev/ce/azure-specific/azure

Create a digger.yml file in the repository root to specify project directories.

```yaml
projects:
- name: infra-prod
  dir: prod
```

--------------------------------

### Standard Digger Workflow Configuration

Source: https://docs.opentaco.dev/ce/features/private-runners

The default workflow configuration using GitHub-hosted runners.

```yaml
name: Digger Workflow
on:
    # ....
jobs:
  digger-job:
    runs-on: ubuntu-latest
```

--------------------------------

### Verify OpenTaco Kubernetes resources

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Use these commands to check the status of pods and services in the opentaco namespace.

```bash
kubectl get pods -n opentaco
kubectl get svc -n opentaco
```
Tokens:
Raw