appeeky spec
← Learn

Teams and CI · 8 min read

How it works with GitHub Actions

What 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.

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

mainlisting/us-fan1 pull requestcheck · diff · comment2 mergepush · commit release3 every dayverify · reviews · playbookday 7day 14
Only the merge touches the stores. The pull request reads git; the daily run reads the stores and writes results back to the repo.

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

bot

Listing changes

storelocalefieldafter
App Storeen-USsubtitleRain, Fan & Baby Sleep Aid
App Storees-MXkeywords+ 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.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

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.yml
# .github/workflows/listing-push.yml
on:
push:
branches: [main]
paths: ["appeeky/store/**", "appeeky.spec.yaml", "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
steps:
- uses: actions/checkout@v4
- run: |
npx @appeeky/spec push --yes --note "${{ github.event.head_commit.message }}"
npx @appeeky/spec social push --yes
npx @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@v4
if: 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.

with your own store keys
- 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.yml
# .github/workflows/listing-daily.yml
on:
schedule: [{ cron: "0 6 * * *" }] # 06:00 UTC
workflow_dispatch:
permissions:
contents: write
jobs:
refresh:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: |
npx @appeeky/spec verify --playbook
npx @appeeky/spec reviews pull
npx @appeeky/spec competitors pull
npx @appeeky/spec social pull
npx @appeeky/spec ugc pull
if [ -n "$GSC_CREDENTIALS" ]; then npx @appeeky/spec seo pull; fi
if [ -n "$ASA_CLIENT_ID" ]; then npx @appeeky/spec search-ads pull; fi
if [ -n "$DATAFORSEO_LOGIN" ]; then npx @appeeky/spec seo ranks --every 7 --yes; fi
if [ -n "$VISIBILITY_EVERY" ]; then npx @appeeky/spec visibility scan --local --every "$VISIBILITY_EVERY" --yes; fi
env:
APPEEKY_API_KEY: ${{ secrets.APPEEKY_API_KEY }}
GSC_CREDENTIALS: ${{ secrets.GSC_CREDENTIALS }} # optional: Google Search Console
ASA_CLIENT_ID: ${{ secrets.ASA_CLIENT_ID }} # optional: Apple Search Ads on your own key
ASA_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 ranks
DATAFORSEO_PASSWORD: ${{ secrets.DATAFORSEO_PASSWORD }}
VISIBILITY_EVERY: ${{ vars.VISIBILITY_EVERY }} # optional: AI answers every N days, on your keys
OPENAI_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

WorkflowSecretsWhy
Pull request checknoneIt only reads git. The built-in GITHUB_TOKEN posts the comment.
Push on mergeAPPEEKY_API_KEY, or your store keysASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY and a Google Play service account.
Daily refreshAPPEEKY_API_KEYFor reviews, competitors, social posts, UGC clips and both stores' ranks. App Store ranks alone work without it.
Clips on your own keyFAL_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 keyASA_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 ranksDATAFORSEO_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 searchGSC_CREDENTIALS (optional)A Search Console service account key. The daily job writes clicks, queries and pages to appeeky/seo/.
AI answers on your keysOPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, PERPLEXITY_API_KEY + the VISIBILITY_EVERY variableAny 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 main with 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
$ # .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: push compares 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 diff shows it as a difference between the files and the store. Run pull to bring their change into the repo, or push to put the files' version back.