PDD GitHub App

A GitHub App that brings PDD (Prompt-Driven Development) directly into your GitHub workflow. Instead of running PDD commands from the CLI, simply label and assign issues to let PDD automatically investigate bugs, implement enhancements, and generate tests -- all from within GitHub.

Prerequisites

Before using the PDD GitHub App, you must register for a PDD Cloud account at https://promptdriven.ai/. Registration provides you with infrastructure credits required to run jobs (infrastructure costs are charged per job execution on Cloud Run).

Installation

1. Visit the GitHub App installation page: https://github.com/apps/prompt-driven-github
2. Click Install
3. Choose the organization or personal account where you want to install the app
4. Select the repositories you want to enable PDD on (or grant access to all repositories)
5. Confirm the installation

Setting Up Repository Secrets (Optional)

You can optionally provide your own LLM API keys as repository secrets. This lets you use your own provider accounts for LLM costs instead of consuming PDD Cloud infrastructure credits.

How to add: Repository → Settings → Secrets and variables → Actions → New repository secret

Supported Secrets

Secret Name	Description	Required
ANTHROPIC_API_KEY	Anthropic API key for Claude models	No*
GOOGLE_API_KEY	Google API key for Gemini models (Google AI Studio)	No*
GEMINI_API_KEY	Alternative Gemini API key (Google AI Studio)	No*
OPENAI_API_KEY	OpenAI API key	No*
CLAUDE_CODE_OAUTH_TOKEN	Claude Code OAuth token	No*

*If you provide your own API key(s), LLM costs are billed directly to your provider account. If you don't provide any keys, the platform uses its managed keys and charges infrastructure credits from your PDD Cloud account.

Note on Gemini model labels: When you use a Gemini model label (pdd-gemini-pro or pdd-gemini-flash), the platform uses its own managed Vertex AI credentials. Your GOOGLE_API_KEY / GEMINI_API_KEY secrets are not used for these jobs -- Vertex AI authentication is handled automatically. Your Google/Gemini API keys are only used when no Gemini model label is applied (i.e., when the PDD CLI selects Gemini as a fallback provider).

The app securely retrieves these secrets at job execution time via an encrypted dispatch workflow (hybrid AES-256-GCM + RSA-OAEP encryption). Secrets are never stored on disk and containers are destroyed after each job.

How It Works

To start a PDD job, simply add a supported label to a GitHub issue. The PDD bot is automatically assigned to the issue and the job is queued.

The app clones your repo, runs the appropriate PDD workflow, and posts results (including a draft PR when applicable) back to the issue.

Triggering a Job

1. Create or open a GitHub issue describing the bug, feature request, or test you need
2. Add a supported label to the issue (see Available Labels below)

That's it -- the bot handles the rest automatically.

Once triggered, the bot will comment on the issue with:

• A Job Queued confirmation with a link to track live progress
• Step-by-step progress updates as it works through the workflow
• A final summary with results and a link to the draft PR (if applicable)

Interacting with a Running Job

You can stop a running job at any time by posting a comment on the issue. Any comment from a non-bot user will immediately stop the current execution. The bot will:

1. Terminate the running job or connect session
2. Remove the trigger label from the issue
3. Post an acknowledgement comment

To restart the job, simply re-add the trigger label. PDD will factor in your latest comments when it runs again, so you can use this to provide additional context, correct the approach, or refine requirements.

Removing the connect or pdd label from an issue with an active connect session will also trigger a graceful shutdown -- the session will auto-commit, push changes, and create a PR before exiting.

Available Labels

You can use either compound labels (a single label that acts as both gate and command) or simple labels with the pdd gate label.

Compound Labels (Recommended)

Label	PDD Command	Description
pdd-bug	fix	Investigate and fix a bug. The agent performs duplicate checking, documentation review, triage, reproduction, root cause analysis, test generation, and creates a draft PR with the fix.
pdd-fix	fix	Alias for pdd-bug -- same behavior.
pdd-change	change	Implement a feature or enhancement described in the issue.
pdd-generate	generate	Generate code for the scenario described in the issue.
pdd-sync	sync	Sync prompts with code.
pdd-connect	connect	Start a connect session.

Simple Labels

Alternatively, add the pdd gate label plus one of these command labels:

Label	PDD Command	Description
bug	fix	Investigate and fix a bug.
fix	fix	Alias for bug -- same behavior.
enhancement	change	Implement a feature or enhancement.
test	test	Generate tests for the functionality or scenario described in the issue.
sync	sync	Sync prompts with code.

Model Selection Labels

Add one of these labels to select a specific model for the job:

Claude Models

Label	Description
pdd-opus	Use the latest Claude Opus (most capable)
pdd-sonnet	Use the latest Claude Sonnet (balanced)
pdd-haiku	Use the latest Claude Haiku (fastest)

Gemini Models (Preview)

Label	Description
pdd-gemini-pro	Use Gemini 3.1 Pro (advanced reasoning, preview)
pdd-gemini-flash	Use Gemini 3 Flash (fastest, preview)

Gemini model labels use the platform's managed Vertex AI infrastructure. No API key setup is required -- authentication is handled automatically via Google Cloud service accounts. See Repository Secrets for details on how API keys interact with model labels.

The platform always resolves model labels to the latest available version. Model labels can be combined with any command label. If no model label is provided, the platform uses its default model.

Note: Labels are case-insensitive.

AI Triage (Automatic)

When a new issue is opened on a repository with the app installed, PDD automatically classifies the issue and may suggest a label. This does not trigger a job -- it only helps with triage. A human must still assign the issue to PDD to start execution.

Example: Bug Fix with PDD GitHub App

Here is a real example of the PDD GitHub App investigating and fixing a bug:

Issue: promptdriven/pdd#533 - pdd bug agents still closes duplicated issues that are not resolved

In this issue, a user reported that the PDD bug agent was incorrectly closing duplicate issues even when the original issue was still unresolved. Once the issue was labeled bug and assigned to PDD, the app:

1. Queued the job and posted a confirmation comment
2. Ran duplicate checking -- confirmed this was a new issue
3. Performed documentation review -- verified it was a legitimate bug
4. Completed triage -- determined sufficient context existed
5. Reproduced the bug using the referenced issues
6. Identified the root cause at a specific line in the orchestrator code
7. Generated a comprehensive test plan with 10 test cases
8. Created failing tests that demonstrate the bug
9. Opened a draft PR (#534) with the test suite

Total execution time: ~24 minutes. The entire investigation was fully automated.

Credit System

PDD GitHub App jobs consume infrastructure credits from your PDD Cloud account:

• Credit usage varies by job complexity
• If you provide your own API keys (see Repository Secrets), LLM costs are billed to your provider account and only infrastructure credits are consumed
• Register at promptdriven.ai to receive initial infrastructure credits

Authorization

Only users with write or admin access to a repository can trigger PDD jobs. The app verifies permissions before queuing any work.

Idempotency

The app tracks completed jobs using markers in issue comments. If a job has already been successfully executed for an issue, re-triggering it (by re-labeling or re-assigning) will not create a duplicate job.

Related Links

• PDD CLI & Documentation: github.com/promptdriven/pdd
• PDD Cloud / Register: promptdriven.ai
• Install the GitHub App: github.com/apps/prompt-driven-github
• GitHub App Source Code: pdd_cloud/pdd_cloud/github_app

Troubleshooting

Problem	Solution
Job not triggering	Ensure the issue has a valid label applied. Check that the app is installed on the repository.
"Insufficient credits" error	Top up your balance at promptdriven.ai.
"Unauthorized" error	Verify you have write or admin access to the repository.
Bot not auto-assigning	Make sure the app is installed on the repository. Visit the installation page to check.
Duplicate job not running	The app prevents duplicate execution. If the issue already has a success marker from a previous run, it will not re-execute.