Purpose

daydream setup installs a review bot in a GitHub repository. The bot runs in the GitHub Actions account of the repository owner. The bot posts as a GitHub App.

The command installs three workflow files. The source package also contains a manual single-file workflow.

Requirements

Install Daydream before you run the setup command.
Install the GitHub command-line interface (gh).
Authenticate gh for the target repository or organization.
Use a Git repository that has a GitHub remote.
Set ANTHROPIC_API_KEY, or use the interactive prompt.
Permit a local web server and browser callback during App registration.
Provide the Blacksmith runner labels that the packaged workflows use.

The packaged workflows use blacksmith-2vcpu-ubuntu-2404 and blacksmith-4vcpu-ubuntu-2404. Change the runs-on values in the setup pull request (PR) if the repository uses different runners.

Install at repository scope

Run this command from a terminal:

daydream setup /work/service --repo acme/service

Replace /work/service with the repository path. Replace acme/service with the GitHub owner and repository.

GitHub requires one manual action. Install the new App when the command opens the installation page. Return to the terminal after the installation is complete.

Install at organization scope

Use --org to store the secrets and variable at organization scope:

daydream setup /work/service --org acme

The command requires exactly one of --repo and --org.

Setup actions

The command performs these actions in order:

It checks for gh and an Anthropic key.
It registers a private GitHub App through the GitHub manifest process.
It waits for the operator to install the App.
It stores three GitHub Actions secrets.
It stores one GitHub Actions variable.
It creates or reuses the daydream/setup-bot branch.
It commits and pushes the workflow files.
It opens a PR against the default branch.

The command does not change the default branch. Merge the setup PR to enable the workflows.

Setup does not undo completed actions after a later failure. A failure can leave an App, secrets, a branch, or a PR. Run the verification command before you repeat setup.

Use --force to register a new App when setup secrets already exist:

daydream setup /work/service --repo acme/service --force

Without --force, setup tries to reuse the stored credentials. Export DAYDREAM_APP_ID and DAYDREAM_APP_PRIVATE_KEY for the local reuse check.

Installed values

The split workflow uses these values. The App identifier (ID) uniquely identifies the GitHub App.

Type	Name	Use
Secret	`DAYDREAM_APP_ID`	Identifies the GitHub App
Secret	`DAYDREAM_APP_PRIVATE_KEY`	Creates short-lived App tokens
Secret	`ANTHROPIC_API_KEY`	Runs the review job
Variable	`DAYDREAM_BOT_HANDLE`	Matches review commands

The manifest requests these repository permissions:

Permission	Access
Pull requests	Read and write
Issues	Read and write
Contents	Read-only
Metadata	Read-only
Actions	Read and write

The Issues permission supports configured issue publication from daydream improve. The split review workflows do not request that permission in their job tokens.

Manual installation

Use these steps when you cannot run daydream setup:

Create a private GitHub App for the target account.
Give the App the permissions in the preceding table.
Generate a private key for the App.
Install the App on the target repository or organization.
Add the three secrets and the bot-handle variable.
Copy the packaged workflow files into .github/workflows/.
Open and merge a PR that contains the workflow change.

Set the App ID as DAYDREAM_APP_ID. Store the complete private key as DAYDREAM_APP_PRIVATE_KEY. Store the review backend key as ANTHROPIC_API_KEY. Set DAYDREAM_BOT_HANDLE without an @ character.

Split workflow

Setup installs these files in .github/workflows/:

File	Function
`daydream-review.yml`	Reviews the pull request and uploads `findings.json`
`daydream-command.yml`	Accepts an authorized review command and starts a review
`daydream-post.yml`	Checks the artifact and posts the findings

The review job checks out pull request code. It receives the Anthropic key but does not receive the App key. The command and post jobs can receive the App key. Those jobs do not check out pull request code.

Reviews start on demand. An owner, member, or collaborator comments the review command. The command workflow dispatches the review with the approved head commit and the comment time. The review job rejects the dispatch when the PR head changes after the approval. There is no automatic trigger on PR open or ready state.

An owner, member, or collaborator can request a review with this comment:

@BOT_HANDLE review

Bot comments do not start a review. The command workflow acknowledges an accepted command with an eyes reaction.

Single-file workflow

The source package contains daydream/templates/workflows/single/daydream.yml. Copy this file manually if you do not use the split workflow. Do not install both variants.

The single-file variant separates untrusted review work from trusted posting work. It does not dispatch a second workflow. Therefore, the App does not require the Actions permission for this variant.

The daydream setup command does not install the single-file variant.

Check an installation

Use the same scope that setup used:

daydream setup /work/service --repo acme/service --verify

Verification is read-only. It always checks these items:

The three secret names and the bot-handle variable exist.
The three split workflow files exist on the default branch.

Verification also checks these items when local App credentials are available:

The App is installed for the target owner.
The App has the required permissions.

GitHub does not return secret values. Verification checks secret names only.

The App installation and permission checks require local App credentials. Verification reports those checks as skipped when the credentials are absent.

Manage repeated comments

A fingerprint is a hidden identifier for a finding. The post job adds a fingerprint to each finding. A later run does not post an exact fingerprint again. The post job marks stale inline comments as outdated when GitHub permits this action.

A changed description can produce a different fingerprint. A finding that appears only in the review body has no comment thread to mark. Daydream removes a stale finding from the next review body.

Source files

Read the current templates in the daydream/templates/workflows directory.

Back to Daydream