Installation

autoducks is runtime-agnostic by design. The agent scripts, provider implementations, and core utilities live in .autoducks/ and are independent of any specific CI/CD platform. The runtime layer — the workflow files that wire triggers to scripts — is a separate concern.

Currently supported runtime: GitHub Actions. Other runtimes are planned.

Note

The instructions below cover the GitHub Actions runtime. If you are setting up on a different CI/CD platform, the .autoducks/ directory installs the same way — only the workflow wiring differs.

Prerequisites (GitHub Actions runtime)

• A repository hosted on GitHub (personal or org)
• gh CLI authenticated (gh auth login)
• An Anthropic API key (from console.anthropic.com)
• The Claude Code GitHub App installed on your repo

One-line install

Run this from the root of your repository:

curl -fsSL https://raw.githubusercontent.com/deepducks/autoducks/main/scripts/install.sh | bash

This downloads the .autoducks/ directory tree and copies the GitHub Actions workflow files to .github/workflows/.

Install options

# Specify a different repo (if not running inside the target repo)
curl -fsSL .../install.sh | bash -s -- --repo OWNER/REPO

# Download files only, skip the setup checks
curl -fsSL .../install.sh | bash -s -- --no-setup

What gets installed

Path	Description
.autoducks/	Agent scripts, prompts, provider implementations, core utilities
.autoducks/runtimes/github-actions/	GitHub Actions workflow definitions (one per agent)
.github/workflows/autoducks-*.yml	Copies of the runtime workflows, placed where GitHub Actions expects them
.github/ISSUE_TEMPLATE/	Issue templates for feature and task issues
scripts/	setup.sh, install.sh, smoke-test.sh

The runtime workflows in .github/workflows/ are copies of the canonical definitions in .autoducks/runtimes/github-actions/. The setup script verifies they stay in sync.

Setup checks

After installing, run scripts/setup.sh to validate your repository:

./scripts/setup.sh

The script checks and auto-creates what it can, and reports what requires manual action:

1. ITS authentication — verifies gh auth status (GitHub CLI). Fatal if missing.

2. Required labels — creates Feature, Ready, Draft, smoke-test, and priority labels if they don’t exist.

3. LLM provider secret — checks that ANTHROPIC_API_KEY is set as a repository secret. If missing, prints the command to add it:

   gh secret set ANTHROPIC_API_KEY --repo OWNER/REPO

4. Runtime workflow permissions — checks for write permissions and can_approve_pull_request_reviews: true on GitHub Actions. Prints the fix command if wrong.

5. Claude Code GitHub App — reminds you to install the app at github.com/apps/claude. Cannot be verified programmatically.

6. Issue types (Feature, Task) — checks org-level issue types. Workflows run without them, but typed issue relationships won’t appear in the issue tracker UI.

7. Runtime workflow sync — verifies that .github/workflows/autoducks-*.yml match .autoducks/runtimes/github-actions/. Fails if out of sync.

Tip

After a successful setup, validate the full pipeline with the smoke test:

./scripts/smoke-test.sh --cleanup

This creates a test feature issue, runs it through the full design → tactical → execution loop, and cleans up afterward.

Updating

Re-run the install script to update to the latest version:

curl -fsSL https://raw.githubusercontent.com/deepducks/autoducks/main/scripts/install.sh | bash

It detects the existing .autoducks/autoducks.json and runs in update mode (skips setup).

Configuration

After installing, you can customize defaults in .autoducks/autoducks.json:

{
  "providers": {
    "its": "github",
    "git": "github",
    "llm": "claude"
  },
  "defaults": {
    "model": "claude-sonnet-4-6",
    "reasoning": "high",
    "base_branch": "main"
  }
}

See Configuration reference for all options.