Runs every day, on GitHub Actions or a server you own

A check on every pull request, a push on merge and a daily pull of everything, on GitHub Actions, any CI, cron or one container on your own machine.

Then ask your agent: “Set up Appeeky Spec for this app.”

Three workflows from one command

One command adds the whole loop to a GitHub repo: a check on every pull request, a push when you merge and a daily run that measures and commits. They are plain workflow files you can read and edit.

init --ci

npx @appeeky/spec init --ci writes them to .github/workflows/. It works on a new spec and on one you already have.

The pull request check runs the appeeky/spec action. It needs the full history to compare with main, and only the right to comment.

listing-check.yml
# .github/workflows/listing-check.yml
on: pull_request
permissions:
contents: read
pull-requests: write # to comment
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the report compares with main
- uses: appeeky/spec@v0

every pull request

listing-check.yml

  1. ✓report
  2. ✓check
  3. ✓comment
  4. ✓ comment on the pull request

The listing fields, check results and keyword coverage before and after, plus the replies, posts and clips the merge would send. Fails when check finds errors.

merge to main

listing-push.yml

  1. ✓push --yes
  2. ✓replies
  3. ✓posts
  4. ✓clips
  5. ✓release file
  6. ✓ live in the stores

Runs when the merge touches the listing, the spec or an approved draft. The commit message becomes the release note.

06:00 UTC

listing-daily.yml

  1. ✓category
  2. ✓visibility
  3. ✓verify --playbook
  4. ✓reviews
  5. ✓competitors
  6. ✓social
  7. ✓ugc
  8. ✓ committed to appeeky/

Pulls everything and measures the releases on day 7 and 14, then commits what changed so your agent reads it next time.

With your own keys the daily run does more:

  • GSC_CREDENTIALS

    seo pull

    Search Console clicks and queries

  • an Apple Search Ads API user

    search-ads pull

    paid searches and spend

  • DATAFORSEO_LOGIN

    seo ranks

    Google ranks, every SEO_RANKS_EVERY days (7)

  • VISIBILITY_EVERY

    visibility scan --local

    asks the assistants every N days on your keys

One run of each

The check on a pull request, the push after the merge and the morning refresh, played out. Click a job or a step to open it.

Merge pull request #43 from listing/us-fan

Push listing

succeeded 2 minutes ago in 3m 55s

  • 1$ npx @appeeky/spec social push --yes
    2✓ 2026-11-12-fan.yaml → x, instagram · Nov 12 16:00 UTC
    3$ npx @appeeky/spec ugc generate --yes --local
    4still Mia in the scene
    5video Mia says the script · 8s 9:16
    6✓ .appeeky/media/2026-11-10-dance.mp4 · uploaded with the run

Every result is a commit

  • a41c09eDaily: category, AI visibility, verify, reviews, competitors, social, UGC
  • 3f2a91cRecord release

appeeky/releases/, the reviews, competitors, the playbook. Your agent reads them the next time it works on the listing.

Checked on day 7 and day 14

pushday 7 ✓day 14 ✓

verify writes the verdict into the release's file. Nobody has to remember the date.

One failure stops nothing

  • ✓ category
  • ✓ visibility
  • ✓ verify
  • ✗ reviews
  • ✓ competitors
  • ✓ social

One source that fails to pull, say reviews, does not stop the rest of the run.

The merge is the only gate

An agent can open as many pull requests as it likes. Nothing reaches the App Store or Google Play until a person merges one.

A pull request can never change the store

The pull request workflow can read the repo and write a comment, nothing else. The push only runs on main, after the merge, and only when the listing or an approved draft changed.

Want a second look before it goes live? The push job runs in a stores environment. Give that environment a required reviewer in the repo settings and each push waits for an approval.

A change the store cannot take yet, like a new App Store name that needs a new version, is reported by diff and waits.

listing-push.yml
# .github/workflows/listing-push.yml
on:
push:
branches: [main]
paths:
- "appeeky/store/**"
- "appeeky.spec.yaml"
- "appeeky/reviews/replies/**"
- "appeeky/social/drafts/**"
- "appeeky/ugc/briefs/**"
permissions:
contents: write # to commit the release file
jobs:
push:
runs-on: ubuntu-latest
environment: stores # optional: a required approval before it runs

The secrets to add

Repository secrets, read by the workflows that need them. Only the first one is needed to start.

  • APPEEKY_API_KEY

    every workflow

    Store access, analytics, reviews and AI visibility through Appeeky. Or your own store keys.

  • FAL_KEY

    push, optional

    Makes UGC clips on your own fal account instead of Appeeky credits.

  • GSC_CREDENTIALS

    daily, optional

    A Search Console service account key, for seo pull.

  • ASA_CLIENT_ID

    daily, optional

    With ASA_TEAM_ID, ASA_KEY_ID and ASA_PRIVATE_KEY, for search-ads pull.

  • DATAFORSEO_LOGIN

    daily, optional

    With DATAFORSEO_PASSWORD: Google ranks every SEO_RANKS_EVERY days (7).

  • VISIBILITY_EVERY

    daily, a variable

    Asks the assistants every N days on OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or PERPLEXITY_API_KEY.

One container on a server you own

Any machine that runs Docker can do what the workflows do: a server of your own, Railway, Fly or Render. Nothing listens on a port; the container only calls GitHub, Appeeky and the stores.

docker compose up -d

Put docker/docker-compose.yml and a .env filled from docker/.env.example in one folder and start it. It runs the routines on a schedule, starts again after a reboot and commits every result back to the repo.

The push routine only pushes listing changes that reach main after it started, so the merge stays the gate. Leave PUSH_DRY_RUN=1 on for the first days to see what it would change.

With a scheduler you already have, like cron, Cloud Run Jobs or Railway cron, run one routine per job: docker run --rm --env-file app.env ghcr.io/appeeky/appeeky-spec daily.

.env
REPO_URL=https://github.com/you/sleep-sounds.git
# Contents: read and write, on this repo only
GITHUB_TOKEN=github_pat_…
APPEEKY_API_KEY=apk_…
# a safe first week: show what a push would change
# PUSH_DRY_RUN=1
# DAILY_AT=0 6 * * *
# PUSH_EVERY=*/15 * * * *
WEEKLY_AT=0 7 * * 1
CLAUDE_CODE_OAUTH_TOKEN=…
HEALTHCHECK_URL=https://hc-ping.com/…
your-server
$ docker compose logs -f
[appeeky-spec schedule] Running on this schedule (UTC):
0 6 * * * appeeky-spec-run daily
*/15 * * * * appeeky-spec-run push
0 7 * * 1 appeeky-spec-run weekly
[appeeky-spec push] Started at 3f2a91c. Listing changes merged from now on are pushed.
[appeeky-spec push] No listing change since 3f2a91c.
[appeeky-spec daily] Committed: Daily: category, AI visibility, search, Search Ads, verify, reviews, competitors, social, UGC
[appeeky-spec push] Committed: Record release
  • dailyonce a day

    The daily pulls and verify, the same as listing-daily.yml, then a commit. Pings HEALTHCHECK_URL, or its /fail when the run fails.

  • pushevery 10–15 minutes

    Pushes listing changes merged to main and commits the release. It remembers the last commit it handled as the appeeky-spec/pushed tag.

  • weeklyonce a week, optional

    The co-founder review. Needs the latest-agent image and CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.

  • schedulestays up

    Runs the three above on DAILY_AT, PUSH_EVERY and WEEKLY_AT. This is what docker compose starts.

GITHUB_TOKEN

  • contents: writethis repo
  • pull requests: writeweekly

It goes to git through a credential helper, never in a URL.

HEALTHCHECK_URL

  • ✓ daily→ping
  • ✗ daily→/fail→email

From healthchecks.io, say: it emails you when a daily run fails or does not happen.

More than one app

services:
  sleep-sounds:
    env_file: sleep-sounds.env
  white-noise:
    env_file: white-noise.env

Copy the service in the compose file and give each its own env file.

Other CI, cron, or nothing at all

Every command runs with npx, so the same three triggers work wherever you already run jobs.

  • GitHub Actions

    init --ci

    The three workflow files, written for you.

  • Docker on a server

    docker compose up -d

    Any VM: Hetzner, DigitalOcean, AWS, Google Cloud, Railway, Fly.io, Render or a machine in your office.

  • GitLabBitbucketCircleCI

    Other CI

    the same three triggers

    A pull request runs report and check, a merge to main runs push --yes, a daily schedule runs the pulls and verify --playbook.

  • crontab

    Your computer

    npx · cron

    Every command runs locally. examples/weekly/weekly.sh runs the weekly review from cron; it needs git with push access, gh, Node 20 and claude.

When a check is missed

Without a schedule, nothing measures the release on day 7. status lists every change being measured, the metric that decides it and the next check, and marks the ones that are late.

It also rewrites appeeky/loops.md, and status --json lists the stores free for a new change.

zsh
$ npx @appeeky/spec status
late 2026-10-31 release · app-store · next 2026-11-07
en-US subtitle: Lead with fan sounds
decided by target ranks
measuring 2026-11-10 release · google-play · next 2026-11-17
en-US title: Say rain sounds first
decided by target ranks
Every store has a release being measured: wait before the next change.
Written to appeeky/loops.md.

A weekly review that cannot push

Once a week the specialists read the repo, and one agent writes a brief and proposes a single listing change as a pull request. It can run on your Claude plan.

It proposes, a person merges

The routine denies the agent every command that pushes, posts, replies, spends credits or reverts. Those wait for the merge, like any other change.

  1. data pull · reviews · competitors · social · ugc

    Refreshes what the specialists read.
  2. status --json

    measuringfree
  3. /appeeky-cofounder

    Your .github/appeeky-propose.md, or the review agents install wrote: commit it first.
  4. listing/weekly-<date>

    A pull request with one change and the brief in appeeky/briefs/. It waits for a person.

The agent may

  • Read, Edit, Write, Glob, Grep
  • subagents (Task, Agent)
  • every other appeeky-spec command
  • git log, git tag

Denied by the routine

  • push
  • revert
  • reviews push
  • social push · reply · hide · like · delete-comment
  • ugc generate --yes
  • visibility scan --local --yes
  • seo ranks · keywords · domain --yes
  • GitHub Actions

    examples/weekly/appeeky-spec-weekly.yml

    Mondays 07:00 UTC

    Pulls the data, asks status for the free stores, runs the review and opens the pull request. A PROPOSAL_TOKEN lets your pull request check run on it.

  • Cron on any machine

    examples/weekly/weekly.sh

    0 7 * * 1 in your crontab

    The same steps, with git, gh, Node 20 and claude installed. A few minutes a week on a laptop, a server or a small VM.

  • Docker

    WEEKLY_AT=0 7 * * 1

    the latest-agent image

    The container that runs the daily and push routines, with Claude Code and gh added. GITHUB_TOKEN needs pull requests write.

The agent

CLAUDE_CODE_OAUTH_TOKENfrom claude setup-token: your Claude Pro or Max plan

or ANTHROPIC_API_KEYbilled per use

The commands

init --ci
Write the pull request check, the push on merge and the daily run to .github/workflows/.
report
Markdown for a pull request: listing changes, check results and coverage against --base.
push --yes
Push without asking. Only for the merge workflow and the server's push routine.
verify --playbook
Measure releases on day 7 and 14 and add what won to the playbook.
status
Every change being measured, the next check, and the ones that are late.
agents install
The specialists and the /appeeky-cofounder review the weekly routine runs.
docker compose up -d
The daily, push and weekly routines on a server of your own.
Every command in the docs

Guides

More in Appeeky Spec