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.
# .github/workflows/listing-check.ymlon: pull_requestpermissions:contents: readpull-requests: write # to commentjobs:check:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4with:fetch-depth: 0 # the report compares with main- uses: appeeky/spec@v0
every pull request
listing-check.yml
- ✓report
- ✓check
- ✓comment
- ✓ 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
- ✓push --yes
- ✓replies
- ✓posts
- ✓clips
- ✓release file
- ✓ 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
- ✓category
- ✓visibility
- ✓verify --playbook
- ✓reviews
- ✓competitors
- ✓social
- ✓ugc
- ✓ 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
.github/workflows/listing-push.ymlPush listing
succeeded 2 minutes ago in 3m 55s
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
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.
# .github/workflows/listing-push.ymlon: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 filejobs:push:runs-on: ubuntu-latestenvironment: 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.
REPO_URL=https://github.com/you/sleep-sounds.git# Contents: read and write, on this repo onlyGITHUB_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 * * 1CLAUDE_CODE_OAUTH_TOKEN=…HEALTHCHECK_URL=https://hc-ping.com/…
$ docker compose logs -f[appeeky-spec schedule] Running on this schedule (UTC):0 6 * * * appeeky-spec-run daily*/15 * * * * appeeky-spec-run push0 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
reportandcheck, a merge to main runspush --yes, a daily schedule runs the pulls andverify --playbook.
crontabYour computer
npx · cron
Every command runs locally.
examples/weekly/weekly.shruns the weekly review from cron; it needs git with push access,gh, Node 20 andclaude.
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.
$ npx @appeeky/spec statuslate 2026-10-31 release · app-store · next 2026-11-07en-US subtitle: Lead with fan soundsdecided by target ranksmeasuring 2026-11-10 release · google-play · next 2026-11-17en-US title: Say rain sounds firstdecided by target ranksEvery 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.
data pull · reviews · competitors · social · ugc
Refreshes what the specialists read.status --json
measuringfree
/appeeky-cofounder
Your .github/appeeky-propose.md, or the review agents install wrote: commit it first.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.
Guides
- Teams and CI · 8 min readHow it works with GitHub ActionsWhat runs on a pull request, on merge and every day, which secrets each step needs, and why a pull request can never change the store.
- Teams and CI · 7 min readRun it on your own VMOne container on a machine you own does what GitHub Actions does: daily pulls, pushes after a merge and the weekly co-founder review.