Compose Multiplatform AdMob SDK + Astro/Starlight docs site. Published to
Maven Central as dev.avinya.ads:admob-cmp; docs live at
https://ads.avinya.dev.
Published Gradle projects (all share a single VERSION_NAME):
admob-cmp/— the user-facing facade. Re-exportsadmob-cmp-coreandadmob-cmp-composeso consumers depend on one coordinate.admob-cmp-core/— shared state machines (consent, slots, banner, native pool) plus Android (GMA Next-Gen) and iOS (GMA 13.x) platform implementations.admob-cmp-compose/— the Compose composables (rememberAdManager,BannerAdView,NativeAdView,AppOpenAdCoordinator).admob-cmp-gradle-plugin/— included build that downloads/links the Google Mobile Ads and UMP iOS XCFrameworks so the consumer's iOS test executables can resolve their cinterops. Consumers apply it asdev.avinya.ads.admob-cmpinpluginManagement.
Sample consumers (do not publish; exist to exercise the SDK end-to-end):
androidApp/, iosApp/, shared/, desktopApp/, webApp/ — the debug-console
demo — and showcase/, the Fieldnotes product-shaped reference module (see
README.md).
Docs site: docs-site/ (Astro + Starlight, deployed to Cloudflare Pages).
Authoritative module guides — read these before editing the library:
- admob-cmp/AGENTS.md — entry points, per-format API, consent flow, iOS setup, troubleshooting, module internals.
- admob-cmp/CLAUDE.md — hard invariants when editing
the library (frozen ABI,
FullScreenSlotCoreownership,Dispatchers.Mainrules, etc.).
Do not restate their content here. If you need to know "how does the SDK work", go read those files.
CI runs no SDK tests. The single GitHub workflow,
.github/workflows/release.yml, runs only on pushes to master and on
workflow_dispatch, and it only publishes, tags, and deploys. There is no
pull-request CI, and no Gradle verification job anywhere in the pipeline —
not even the Ubuntu-runnable ones. The sole test step in CI is docs-site's
own Vitest suite. If you do not verify the SDK locally, nobody and nothing
will.
Before opening a PR, all four of the following must happen, in order:
- Run
./scripts/release-readiness.shand get a cleanREADINESS: PASS. The script is the only verification that exists in this project (Android host tests + publication metadata; the Central task graph; iOS tests + klib ABI; Maven Local publish + shared consumer round trip; the Xcode consumer build; and the docs section — Dokka + Astro + verify).--skip-docsis acceptable when the change does not touchadmob-cmp/,admob-cmp-core/,admob-cmp-compose/,gradle/libs.versions.toml,gradle.properties, ordocs-site/. - Report the result to the owner and ask for explicit confirmation before opening the PR. Do not open it unilaterally. Include which sections ran, which were skipped, and anything that failed and was fixed.
- If you cannot run the script locally (no macOS / no Xcode 26), say so and stop. There is no remote fallback — no workflow will verify the branch for you. Do not open the PR describing it as verified.
- A
READINESS: PASSis not authorisation to open the PR — it is a prerequisite for asking. The owner decides whether to open it.
Do not add verification jobs to release.yml, including as a gate in
front of publish, and including cheap Ubuntu-only ones. Keeping CI free of
SDK tests is a standing decision, not an oversight. If coverage needs to
move, it moves into scripts/release-readiness.sh.
The library's public ABI is frozen (see invariant 12 in admob-cmp/CLAUDE.md). Additive changes are fine; breaking changes need a written migration plan for every consuming app.
After any change to the public surface of admob-cmp-core or
admob-cmp-compose:
./gradlew :admob-cmp-core:updateKotlinAbi
./gradlew :admob-cmp-compose:updateKotlinAbiCommit the regenerated api/*.klib.api dump in the same commit as the
change. Nothing in CI will catch a stale dump — checkKotlinAbi runs
only in scripts/release-readiness.sh, so a missed updateKotlinAbi merges
and publishes silently.
Bumping VERSION_NAME in both gradle.properties and
admob-cmp-gradle-plugin/gradle.properties (in lockstep) is the only
thing that triggers a release. Do it deliberately, in its own commit, as
the last commit of a release-worthy change.
On merge to master, release.yml:
- Waits for approval. The
publishjob is bound to the protectedmaven-centralenvironment, so it does not start until a required reviewer approves it in the Actions run. A version bump therefore does not publish on its own — if nobody approves, the release sits pending and nothing is uploaded or tagged. The environment name is the half that lives in code; the required reviewers are configured in repository settings. - Generates the provenance assets (checksum manifest + SPDX SBOM) and attests both, before anything is uploaded. Nothing there reads the deployment, and the upload is the only irreversible step, so a provenance failure must not be able to leave a published-but-untagged version behind.
- Publishes two staging deployments to Maven Central via
./admob-cmp/scripts/publish-maven-central.sh(library + Gradle plugin — they are two separate Gradle builds, so two deployments). It runs no tests first. - Creates an annotated tag named exactly
<version>(novprefix). - Cuts a GitHub release with auto-generated notes and a header line pointing at the manual Central Portal step.
In parallel, and independently of the release path, it regenerates the Dokka
API reference (api-reference, macOS) and rebuilds and deploys the docs site
(docs-site, Ubuntu).
Manual step the pipeline does not do: both staging deployments must be
released manually in Central Portal
before the artifacts are publicly available. The pipeline's release notes
and the publish job's summary both say this. mavenCentralAutomaticPublishing
stays false — Maven Central coordinates are immutable, so this last human
step is deliberate.
Never create tags or GitHub releases by hand. release.yml owns them.
A hand-made tag will make the next run early-exit and skip the release
entirely.
A push that changes neither the version nor any docs input
(docs-site/, admob-cmp/, admob-cmp-core/, admob-cmp-compose/,
gradle/libs.versions.toml, gradle.properties, or the workflow file
itself) exits in seconds on the gate job. That is expected, not a
failure — it is the steady state.
If the release changes native integration, consent, presentation, the renderer, or Gradle/XCFramework behaviour, run and sign docs/release/device-certification.md. The local suite cannot prove any of it — every row depends on real GMA/UMP behaviour, real OS lifecycle, or real network conditions.
Maven Central is immutable; there is no rollback. Follow docs/release/hotfix-playbook.md.
No dependency version is bumped on a successful compile alone. For any GMA or
UMP bump: read the upstream release notes for API, threading, linker, and
consent changes; re-run the mapper characterization tests
(AndroidAdMappersTest, IosAdMappersTest); re-run
scripts/release-readiness.sh in full; recompute the iOS archive checksums
deliberately; and run device certification for every affected format. For a
Kotlin, KGP, Gradle, AGP, or Compose bump, additionally run
./scripts/distribution/verify-published-release.sh <version> --local before
changing anything in
docs-site/src/content/docs/reference/compatibility.mdx.
Maven Central artifacts are immutable. Once the publish job completes, run
the canary from a clean room:
./scripts/distribution/verify-published-release.sh <version>This generates a throwaway KMP consumer in a temp directory that resolves
dev.avinya.ads:admob-cmp and the Gradle plugin from Maven Central only — no
mavenLocal(), no project substitution, no access to this source tree. It is
the only check that exercises the path a real consumer uses.
A failure is not recoverable by rollback. Follow docs/release/hotfix-playbook.md.
The same script with --local is the pre-release clean-room check, and is
worth running after publishToMavenLocal whenever publication metadata,
coordinates, or the Gradle plugin change.
docs-site/public/api/ is generated by ./gradlew syncApiDocsToDocsSite
and gitignored. Never commit it. The same applies to docs-site/dist/.
The Astro build itself runs on ubuntu-latest in CI, but the Dokka
generation it depends on runs on macos-26 because Apple's iOS cinterop
needs the Xcode-provided iOS SDK headers, which a Linux runner does not
have. This is why the pipeline splits api-reference (macOS) and
docs-site (Ubuntu) into two jobs with an artifact handoff.
Local docs work only needs Node — cd docs-site && npm ci && npm run build && npm test && npm run verify is sufficient to validate Astro changes once
./gradlew syncApiDocsToDocsSite has populated docs-site/public/api/.
Build before test, not the other way round — some Vitest cases assert
against rendered dist/ output and hard-fail rather than skip when it is
absent. Test-before-build shipped for a while and looked fine locally
because a stale dist/ from an earlier manual build was still on disk; a
truly clean tree, including CI, fails.
Read docs-site/DESIGN.md before changing tokens.css, landing.css or
diagrams.css. It records what the design system is for, which colour
pairings are contrast-enforced, and the traps that have already been hit
once. The gates catch broken mechanics; they cannot tell you the intent.
It is an internal note and is not part of the built site.