suede-play-release

Files (4)

• CARD.md
• SKILL.md
• openai.yaml · agents/
• play-preflight.py · scripts/

SKILL.md (first lines)

# Suede AI Google Play Release Skills

## Compatibility

Requires Android release artifacts and authorized Google Play publishing access. Bundled preflight uses Python with pyjwt/cryptography and macOS Keychain; delivery examples use fastlane supply. Linux CI uses its secret store.

Use [the worked contract](references/worked-contract.md) for a staged rollout
example, access-failure recovery, and API readback validation.

```text
Iron Law: the Play API decides what shipped, not a green fastlane summary.
Every claim about a live release is a readback or it is a guess.
```

## Gate policy: advisory, not blocking

Run every check and report results honestly. Verdicts are advice attached to the
work, never a control that changes it. A failed check changes what you report,
never what you do. The one exception is the production halt in Step 7: a public
release is irreversible for the users who get it, so present the options and let
the user pick.

## Step 0: Preflight the credential before anything else

Never assume publishing works. Prove it with a real API call that changes
nothing: open an edit and delete it. The script reads the key from the macOS
login Keychain and needs `pyjwt` and `cryptography`; on Linux CI, load the same
base64 JSON from the CI secret store and run the equivalent token exchange.

```bash
python3 scripts/play-preflight.py <package.name> [--service NAME] [--account NAME]
```

Three outcomes, three different actions:

| Result | Meaning | Do |
| --- | --- | --- |
| token fails | key is wrong or revoked | rotate, see Step 1 |
| HTTP 401/403 on the edit | Play Console has not granted the account | Step 1's grant |
| edit opens and deletes | publishing is wired | continue |

A 403 here is the normal state of a brand-new service account, not a bug.

## Step 1: Credentials

Use a **dedicated publishing service account**, separate from any billing or
purchase-verification account. A credential that can push releases should not
also be able to void purchases. Give it no cloud IAM roles: all of its authority
comes from the Play Console grant, so before that grant the key is inert.

Store the JSON in the login Keychain **base64-encoded**:

```bash
security add-generic-password -U -s GOOGLE_PLAY_SERVICE_ACCOUNT_JSON -a <account> -w
```

Run it with `-w` last and no value so it prompts and the key never enters shell
history. Paste the base64, not the raw JSON.

Base64 is load-bearing. `security` hex-encodes any multi-line secret on read, so
raw JSON comes back in one of two shapes depending on content. Base64 gives one
shape and one decode path.

Granting access is a **Play Console UI action** and cannot be done from the API:
invite the service-account email under Users and permissions with release
permissions on the app. Report this to the user as a step only they can take,
with the exact email and permissions, then re-run Step 0.

## Step 2: Pull before every command

`fastlane` reads the working tree, not the remote. A stale checkout produces a
run that succeeds and does nothing, because a missing changelog is a skip rather
than an error.

```bash
git -C <repo> pull --ff-only && git -C <repo> log --oneline -1
```

If fastlane offers to set itself up, the Fastfile is not on disk. Answer no and
pull; accepting scaffolds an empty config over the real one.

## Step 3: Write the changelog first

Release notes live at
`fastlane/metadata/android/<locale>/changelogs/<versionCode>.txt`, one file per
locale per versionCode.

A missing file is **not** an error. Play silently serves the previous version's
notes, so users read stale text against a new build and nothing tells you. Write
one for every locale that has listing copy, before uploading.

```bash
for l in $(ls fastlane/metadata/android); do
  [ -f "fastlane/metadata/android/$l/changelogs/$VC.txt" ] || echo "MISSING: $l"
done
```

Match each locale's existing register rather than translating the English word
for word. Check the limit: 500 characters.

## Step 4: Verify the artifact, never the source tree

A source read is not evidence that a change reached the binary.

```bash
jarsigner -verify app/build/outputs/bundle/release/app-release.aab | head -1
grep -oE 'android:version(Code|Name)="[^"]*"' \
  app/build/intermediates/merged_manifests/release/*/AndroidManifest.xml
```

When the release changes an asset, hash it on both sides and require a match:

```bash
unzip -p <aab> 'base/res/*xxxhdpi*ic_launcher.png' | shasum -a 256
shasum -a 256 app/src/main/res/mipmap-xxxhdpi/ic_launcher.png
```

`jarsigner` reporting a self-signed certificate is correct under Play App
Signing, which re-signs with the real release key.

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills