The spec runs the same commands everywhere: your terminal, your agent, CI. GitHub Actions only decides when they run. There are three moments, and each one does a different job.
The short version
01
Pull request
on: pull_request
Checks the listing, comments what will change and the coverage, fails on errors.
needs nothing
02
Merge
on: push to main
Pushes the change to App Store Connect and Google Play and commits the release record.
needs store access
03
Every day
on: schedule
Measures releases on day 7 and 14, pulls reviews and competitors, updates the playbook.
needs APPEEKY_API_KEY
You can use any of them on its own. Most teams start with the pull request check, add the push once they trust it, and add the daily run when they want results to arrive by themselves.
On every pull request
The Action appeeky/spec@v0 runs appeeky-spec report against main: it runs check on the listing in the branch, lists every field that changed, and compares keyword coverage before and after. Then it posts that as a comment, updating the same comment on every new commit:
appeeky-spec commented on #43
botListing changes
| store | locale | field | after |
|---|---|---|---|
| App Store | en-US | subtitle | Rain, Fan & Baby Sleep Aid |
| App Store | es-MX | keywords | + fan |
✓ check 0 errors · 1 warning · coverage us 4/5 → 5/5
If check finds an error (a subtitle over 30 characters, a keyword field over 100), the job fails, so a required status check blocks the merge. Warnings are reported but do not fail it.
# .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
On merge: push to the stores
This is the only step that changes the live listing. When a change lands on main, a second workflow runs push --yes: it checks again, saves today's ranks as the baseline, pushes, and writes appeeky/releases/<date>.yaml. The job commits that file back so the history stays in git.
# .github/workflows/listing-push.ymlon:push:branches: [main]paths: ["appeeky/store/**", "appeeky.spec.yaml", "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 runssteps:- uses: actions/checkout@v4- run: |npx @appeeky/spec push --yes --note "${{ github.event.head_commit.message }}"npx @appeeky/spec social push --yesnpx @appeeky/spec ugc generate --yes ${FAL_KEY:+--local}env:APPEEKY_API_KEY: ${{ secrets.APPEEKY_API_KEY }}FAL_KEY: ${{ secrets.FAL_KEY }} # optional: clips on your own fal account- uses: actions/upload-artifact@v4if: hashFiles('.appeeky/media/*.mp4') != ''with: { name: ugc-clips, path: .appeeky/media/*.mp4 }- run: |git config user.name "appeeky-spec"git config user.email "spec@users.noreply.github.com"git add appeeky && git commit -m "Record release, posts and clips" && git push || true
The commit message becomes the release's note, so write it as the reason: “Lead with fan sounds”. With your own store keys instead of Appeeky, replace the push step with the one below. The same job sends the social posts and makes the UGC clips a merged pull request approved; see Posts and videos through pull requests.
- run: printf '%s' "$PLAY_JSON" > "$RUNNER_TEMP/play.json"env: { PLAY_JSON: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT }} }- run: npx @appeeky/spec push --yes --note "${{ github.event.head_commit.message }}"env:ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}ASC_PRIVATE_KEY: ${{ secrets.ASC_PRIVATE_KEY }}GOOGLE_APPLICATION_CREDENTIALS: ${{ runner.temp }}/play.json
Every day: measure and refresh
Results come in on their own schedule. A daily job runs verify --playbook, which only acts on releases that reached day 7 or day 14, and pulls fresh reviews, competitors, social posts and UGC clips. Whatever changed is committed, so the next proposal, yours or your agent's, starts from it.
# .github/workflows/listing-daily.ymlon:schedule: [{ cron: "0 6 * * *" }] # 06:00 UTCworkflow_dispatch:permissions:contents: writejobs:refresh:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- run: |npx @appeeky/spec verify --playbooknpx @appeeky/spec reviews pullnpx @appeeky/spec competitors pullnpx @appeeky/spec social pullnpx @appeeky/spec ugc pullif [ -n "$GSC_CREDENTIALS" ]; then npx @appeeky/spec seo pull; fiif [ -n "$ASA_CLIENT_ID" ]; then npx @appeeky/spec search-ads pull; fiif [ -n "$DATAFORSEO_LOGIN" ]; then npx @appeeky/spec seo ranks --every 7 --yes; fiif [ -n "$VISIBILITY_EVERY" ]; then npx @appeeky/spec visibility scan --local --every "$VISIBILITY_EVERY" --yes; fienv:APPEEKY_API_KEY: ${{ secrets.APPEEKY_API_KEY }}GSC_CREDENTIALS: ${{ secrets.GSC_CREDENTIALS }} # optional: Google Search ConsoleASA_CLIENT_ID: ${{ secrets.ASA_CLIENT_ID }} # optional: Apple Search Ads on your own keyASA_TEAM_ID: ${{ secrets.ASA_TEAM_ID }}ASA_KEY_ID: ${{ secrets.ASA_KEY_ID }}ASA_PRIVATE_KEY: ${{ secrets.ASA_PRIVATE_KEY }}DATAFORSEO_LOGIN: ${{ secrets.DATAFORSEO_LOGIN }} # optional: Google ranksDATAFORSEO_PASSWORD: ${{ secrets.DATAFORSEO_PASSWORD }}VISIBILITY_EVERY: ${{ vars.VISIBILITY_EVERY }} # optional: AI answers every N days, on your keysOPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}- run: |git config user.name "appeeky-spec"git config user.email "spec@users.noreply.github.com"git add appeeky && git commit -m "Daily: verify, reviews, competitors, social, UGC, search" && git push || true
Your analytics and revenue (data pull) are left out on purpose: they are private and live in the gitignored .appeeky/data/. Pull them where you work, or set data: { commit: true } in a private repo.
Which secrets go where
| Workflow | Secrets | Why |
|---|---|---|
| Pull request check | none | It only reads git. The built-in GITHUB_TOKEN posts the comment. |
| Push on merge | APPEEKY_API_KEY, or your store keys | ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY and a Google Play service account. |
| Daily refresh | APPEEKY_API_KEY | For reviews, competitors, social posts, UGC clips and both stores' ranks. App Store ranks alone work without it. |
| Clips on your own key | FAL_KEY (optional) | The push job makes UGC clips with ugc generate --local and fal bills you, instead of Appeeky media credits. |
| Search Ads on your own key | ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_PRIVATE_KEY (optional) | An Apple Search Ads API user. The daily job writes spend, installs, keywords and search terms to appeeky/search-ads/. |
| Google ranks | DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD (optional) | Your DataForSEO account. Once a week the daily job checks where the site and the store page rank on Google, and AI Overview citations. |
| Google search | GSC_CREDENTIALS (optional) | A Search Console service account key. The daily job writes clicks, queries and pages to appeeky/seo/. |
| AI answers on your keys | OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, PERPLEXITY_API_KEY + the VISIBILITY_EVERY variable | Any of the keys. The daily job asks the assistants every N days with visibility scan --local; each provider bills you. |
Add them under Settings → Secrets and variables → Actions. With APPEEKY_API_KEY, your store keys stay in Appeeky and never reach GitHub at all.
Who can change the listing
Pushing is tied to merging, so GitHub's own controls decide who can change the store:
- Branch protection on
mainwith the check as a required status: nothing with check errors can merge. - CODEOWNERS for
/appeeky/and/appeeky.spec.yaml: a listing change needs a review from your growth team. - An environment (
environment: stores) with required reviewers: one more approval right before the push job runs.
$ # .github/CODEOWNERS$ /appeeky/ @your-org/growth$ /appeeky.spec.yaml @your-org/growth
Agents fit the same way: they open a pull request, the check comments on it, a person approves it, and the merge ships it. The spec has no approval step of its own; your pull request review is the approval.
Common questions
- Do I need GitHub Actions at all?
- No. Every command runs from your terminal or your agent. Actions only runs them for you at the right moment. Any CI works the same way: GitLab, CircleCI, a cron job, or one container on your own VM (see Run it on your own VM).
- Can a pull request change my live listing?
- No. The pull request check never talks to the stores. Only the push workflow on main does, after the merge.
- What if the push fails halfway?
- The job fails and nothing is committed. Fix the cause and re-run it:
pushcompares with the live store each time, so it only sends what is still different. - Someone edited the listing in App Store Connect. Now what?
- The next
diffshows it as a difference between the files and the store. Runpullto bring their change into the repo, or push to put the files' version back.