Install Paidwen on a repository

Paidwen verifies each pull request by running it in your own GitHub Actions runner. The setup takes one command, or six steps by hand. Every step happens in your repository on GitHub, and Paidwen never reads your code.

Install Paidwen in one command

1. Install the Paidwen GitHub App on the repository: https://github.com/apps/paidwen.
2. Run this command in the folder of the repository:

npx paidwen setup

The command adds the Paidwen workflow and paidwen.yml to the default branch. It drafts paidwen.yml from the stack of the folder. It creates the paidwen environment, asks for the secrets your journeys need, and requires the Paidwen check. It uses your own GitHub sign in, from the gh command or from GITHUB_TOKEN, so the Paidwen app keeps its permissions and never reads your code.

When the default branch refuses direct commits, the files wait in a pull request from the branch paidwen-setup. Merge it to finish. The command changes only what is missing, so you can run it again at any time. In Claude Code, the Paidwen plugin runs it with /paidwen:setup.

Install Paidwen in one click

The Installation tab of a repository in the dashboard also offers Install in one click. It asks you to install Paidwen Setup, a second GitHub App that can write to the repository you pick. Paidwen Setup adds the same two files, creates the paidwen environment and requires the Paidwen check, then removes itself. Its paidwen.yml opens the home page only: record your real journeys afterwards.

The Paidwen app itself never gets write access. Choose the command when nothing should write to your repository.

The six steps below do the same setup by hand.

1. Install the Paidwen GitHub App

Open https://github.com/apps/paidwen, click Install, then choose the account and the repositories to verify.

The app asks for these permissions:

• Metadata: read.
• Pull requests: write, for the single verdict comment.
• Checks: write, for the Paidwen check.
• Actions: write, to start, cancel and read the runs of the Paidwen workflow.
• Merge queues: read, to give a merge queue the verdict of the pull requests it holds.

The app has no Contents permission, and the servers of Paidwen never request the diff of a pull request.

2. Add the Paidwen workflow

Create .github/workflows/paidwen.yml on your default branch with this content. The file is the same for every repository.

name: Paidwen
run-name: "Paidwen verification of pull request #${{ inputs.pr }}"
on:
  workflow_dispatch:
    inputs:
      verification:
        description: Verification
        type: string
        required: true
      pr:
        description: Pull request
        type: string
        required: true
      head:
        description: Head commit
        type: string
        required: true
      base:
        description: Base commit
        type: string
        required: true
      environment:
        description: Environment
        type: choice
        options:
          - paidwen
          - paidwen-fork
        required: true
      api:
        description: Paidwen API
        type: string
        required: true
permissions:
  contents: read
  id-token: write
jobs:
  verify:
    uses: RaselisonToky/paidwen-action/.github/workflows/verify.yml@v1
    secrets: inherit
    with:
      verification: ${{ inputs.verification }}
      pr: ${{ inputs.pr }}
      head: ${{ inputs.head }}
      base: ${{ inputs.base }}
      environment: ${{ inputs.environment }}
      api: ${{ inputs.api }}

Paidwen starts this workflow on your default branch for each pull request, so a pull request cannot change the workflow that verifies it. The workflow never runs on push or on pull_request.

The job asks for two permissions. contents: read checks out the pull request without keeping the credentials. id-token: write lets the job prove to Paidwen which repository and which run is asking.

The job runs on ubuntu-latest. A large app builds faster on a larger runner: add runs-on under with:, set to the label of the runner, or to a JSON list of labels for a self-hosted runner, such as '["self-hosted", "linux"]'; a self-hosted runner needs the Scale or Enterprise plan, as the section on your own runner explains. On a GitHub-hosted runner, the job first frees disk space when less than 40 GB is left.

If your organization or repository allows only selected actions and reusable workflows, add these two patterns under Allow specified actions and reusable workflows:

• RaselisonToky/paidwen-action@* allows the action.
• RaselisonToky/paidwen-action/.github/workflows/verify.yml@* allows the reusable workflow that your Paidwen workflow calls. GitHub matches a reusable workflow with its own pattern, so the first pattern does not cover it.

Then turn on Allow actions created by GitHub, or add actions/checkout@* and actions/upload-artifact@* to the same list.

3. Add paidwen.yml

paidwen.yml tells Paidwen how to start your application and which user journeys to replay. This command writes a first version at the root of your repository:

npx paidwen init

Commit the file on your default branch. Paidwen reads it from the base branch of each pull request. The reference of every field is at https://paidwen.com/docs/paidwen-yml.

4. Create the paidwen environment and its secrets

1. Open Settings, then Environments, then New environment, and name it paidwen.
2. Under Deployment branches and tags, choose Selected branches and tags, then add your default branch. Only the jobs that run on the default branch can then read the secrets.
3. Name the environment paidwen in no other workflow of the repository. The branch rule filters branches, not workflows. Any job that runs on the default branch and names this environment reads its secrets.
4. Under Environment secrets, add the secrets your paidwen.yml needs.

Paidwen reads only these names:

• PAIDWEN_TEST_LOGIN and PAIDWEN_TEST_PASSWORD: the test account of the journeys with account: true.
• PAIDWEN_STRIPE_TEST_KEY: your Stripe test secret key, when services.stripe is test.
• PAIDWEN_ENV: a dotenv block, one KEY=value per line, given to every service of your application.
• PAIDWEN_MODEL_KEY: your own Anthropic API key, for the optional model layer that records a journey written as a goal, repairs a journey changed on purpose and explains a break in one sentence. Only the engine reads it, never your application. See https://paidwen.com/docs/paidwen-yml.

The GitHub CLI sets the same secrets once the environment exists:

gh secret set PAIDWEN_TEST_LOGIN -e paidwen
gh secret set PAIDWEN_TEST_PASSWORD -e paidwen

Keep these secrets in the environment. The workflow also receives the repository and organization secrets through secrets: inherit, and a secret of the environment wins over a secret of the same name.

5. Make the Paidwen check required

With a ruleset:

1. Open Settings, then Rules, then Rulesets, then New ruleset, then New branch ruleset.
2. Target your default branch.
3. Turn on Require status checks to pass, click Add checks, choose Paidwen, and pick the Paidwen app as its source.

With a classic branch protection rule, open Settings, then Branches, add a rule for your default branch, turn on Require status checks to pass before merging, and select Paidwen.

On a private repository, required checks and environments need GitHub Pro, GitHub Team or GitHub Enterprise.

A neutral check counts as passed. When Paidwen itself cannot verify a pull request, the check is neutral and the merge stays possible.

6. Open a first pull request

1. Open a pull request against your default branch.
2. The Paidwen check appears on the pull request within seconds.
3. About 90 seconds after the last commit, Paidwen starts the workflow. The run appears in the Actions tab as "Paidwen verification of pull request #" followed by its number.
4. When the run ends, the check passes or fails, and a single comment shows five lines and the link to the video.

The run itself never fails because of Paidwen. When Paidwen cannot verify, the run writes one line in its log and ends, and the Paidwen check reports that Paidwen could not verify the pull request.

Pull requests from forks run without secrets

A pull request from a fork runs in the environment paidwen-fork, without any secret. GitHub creates this environment on the first run. Never add a secret to it.

The pull request of a first-time contributor from a fork waits until a maintainer clicks Verify on the Paidwen check.

Paidwen works on github.com with every GitHub plan

Paidwen works for personal accounts and organizations on github.com, from GitHub Free to GitHub Enterprise Cloud. It does not work with GitHub Enterprise Server, nor with GitHub Enterprise Cloud on a GHE.com domain.

On a private repository of GitHub Free, GitHub offers neither required checks nor environment secrets. The Paidwen check shows the verdict but does not block the merge. Add the secrets of step 4 as repository secrets: the Paidwen workflow reads them through secrets: inherit. Every other workflow of the repository can read them too, so give Paidwen a test account only.

An enterprise that issues its OIDC tokens from its own address, https://token.actions.githubusercontent.com/ followed by its slug, has nothing to change.

An IP allow list needs one setting

If your organization or your enterprise restricts access with an IP allow list, open its settings, then Authentication security, and turn on Enable IP allow list configuration for installed GitHub Apps. GitHub then adds the address of Paidwen to your list, and Paidwen can post its check and start its workflow.

The standard GitHub-hosted runners have no fixed address, so they cannot check out a repository behind an IP allow list. Set runs-on to a larger GitHub runner with a static address, on any plan, or to your own runner on the Scale and Enterprise plans.

Your own runner needs the Scale or Enterprise plan

On the Scale and Enterprise plans, the verification can run on your own runner: a self-hosted runner in your cloud, or a runner from a provider such as Blacksmith, Depot, Namespace or BuildJet. GitHub counts both as self-hosted. On the Open source and Team plans, a run on a self-hosted runner gets a neutral verdict, which never blocks the merge. The larger runners of GitHub are hosted by GitHub, so every plan can use them.

Set runs-on under with: in .github/workflows/paidwen.yml, to the label of the runner or to a JSON list of labels, such as '["self-hosted", "linux"]'.

The machine needs:

• Linux, with bash.
• Docker, with the compose plugin.
• Node.js 20 or later on the PATH.
• About 40 GB of free disk.
• Outbound HTTPS to api.paidwen.com, github.com and the registries of your images.

Never use a self-hosted runner for a public repository. The verification runs the code of each pull request on the runner, the pull requests from forks included.

The verification uses your GitHub Actions minutes

The verification runs on your runner, so it uses your GitHub Actions minutes. A verification takes about 3 to 4 minutes on the standard runner of a public repository. We measured 3 minutes for a pull request that works and 3 minutes 34 seconds for one that breaks a journey, replay on the base branch included.

Public repositories do not pay for these minutes. In a private repository, the minutes count toward the minutes included in your GitHub plan, then GitHub bills them. The standard runner of a private repository has fewer cores, so a verification can take longer there.