DOCSEARCHbyAlgolia
Submit Docs

greenlight

repository·main·Indexed 25 days ago

https://github.com/revylai/greenlight

A pre-submission compliance scanner for the Apple App Store and Google Play. It analyzes source code, manifests, and binaries to ensure compliance with platform guidelines. Features include static analysis via codescan and playscan, privacy compliance checks, iOS IPA inspection, App Store Connect API checks, and runtime flow verification via the Revyl CLI.

Tokens
12.3K
Snippets
34
Records
78
Agent score
80%

What's inside greenlight

  1. Use greenlight verify for runtime validation

    main

    While static scans (like codescan) check text and structure, greenlight verify performs runtime flow validation on cloud devices using Revyl. This catches issues that static analysis cannot see, such as a button that is present in code but performs no action when tapped.

    Key flows covered by verify:

    • account-deletion: Ensures the account is actually deleted (§5.1.1).
    • restore-purchases: Ensures the Restore Purchases flow is not a no-op (§3.1.1).
    • sign-in-apple: Ensures the Apple sign-in sheet actually appears (§4.8).

    You can run a --dry-run to see the tests that would be executed without requiring a device or an account.

    greenlight verify . --dry-run   # free, offline, shows you the tests it would run

  2. Understand greenlight severity levels

    main

    Greenlight categorizes findings into four severity levels. When using the --exit-code flag, only CRITICAL and HIGH levels will trigger a failure.

    LevelMeaning
    CRITICALRejection or install failure is near-certain. Fix before you submit.
    HIGHA published deadline, a required declaration, or a check that fails at runtime.
    WARNLikely to draw reviewer attention or an information request.
    INFOBest practice.

    Note: An incomplete scan (e.g., due to a scanner crash) will also trigger a failure when --exit-code is used.

  3. Understand greenlight severity levels

    main

    Greenlight findings are categorized by severity. Your goal is to reach GREENLIT status, which means having zero CRITICAL findings.

    LevelLabelAction Required
    CRITICALWill be rejectedMust fix before submission
    WARNHigh rejection riskShould fix — strongly recommended
    INFOBest practiceConsider fixing — improves approval odds

  4. Silence specific findings with inline directives

    main

    To suppress a specific rule on a single line rather than disabling the entire rule globally, use an inline directive in your source code. You can name the specific rule to keep other checks active, or use a bare directive to suppress everything on that line.

    let host = "10.1.2.3" // greenlight:ignore hardcoded-ipv4

  5. Integrate Greenlight with GitHub Actions and SARIF

    main

    You can upload Greenlight SARIF reports to GitHub Code Scanning to see findings in the Security tab and inline on pull requests. To gate your CI job on CRITICAL or HIGH findings (or scanner crashes), use the --exit-code flag.

    To keep a JSON report as a CI artifact, combine --format json, --output <file>, and --exit-code.

    # Upload SARIF to GitHub
- run: greenlight preflight . --format sarif --output greenlight.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: greenlight.sarif

# GitHub Actions: Fail on CRITICAL/HIGH findings
- name: App Store + Play compliance
  run: greenlight preflight . --exit-code

# GitHub Actions: Fail and save JSON report
- run: greenlight preflight . --format json --output greenlight-report.json --exit-code

# GitHub Actions: Gate on runtime tier (requires authenticated revyl CLI on PATH)
- run: greenlight preflight . --verify --build-name "My App" --exit-code

  6. Install Greenlight as a Codex skill

    main

    To use Greenlight in Codex, install the skill package into your Codex skills directory.

    mkdir -p ~/.codex/skills/app-store-preflight-compliance
cp -R codex-skill/* ~/.codex/skills/app-store-preflight-compliance/

  7. Validate app flows at runtime with greenlight verify

    main

    While preflight performs static analysis, greenlight verify performs runtime validation of flow-dependent guidelines (like account deletion or in-app purchases) on cloud devices. This requires the revyl CLI, a Revyl account (revyl auth login), and a registered build.

    Dry run (See claimed flows and tests)

    greenlight verify . --dry-run

    Run flows on a cloud device

    Use a registered build name and provide credentials via --var:

    greenlight verify . --build-name "<your Revyl build>" \
  --var email=<test account> --var password=<test password>

    Run a local build using an artifact

    If your build is not yet on Revyl, you can upload a simulator .app (iOS) or .apk (Android) directly:

    greenlight verify . --build-name "<your Revyl build>" --artifact ./build/MyApp.app \
  --var email=<test account> --var password=<test password>

    Verification Results

    • VERIFIED: The flow works correctly.
    • FAILED: The flow passed static analysis but broke at runtime (e.g., a button is non-functional). This is treated as a CRITICAL issue.
    • SETUP: Could not run due to authentication, missing build, or device issues.
    greenlight verify . --dry-run

greenlight verify . --build-name "<your Revyl build>" \
  --var email=<test account> --var password=<test password>

greenlight verify . --build-name "<your Revyl build>" --artifact ./build/MyApp.app \
  --var email=<test account> --var password=<test password>

  8. Install the greenlight CLI

    main

    If greenlight is not found in your PATH, you can install it using Homebrew, Go, or by building from source.

    Homebrew (macOS)

    brew install revylai/tap/greenlight

    Go install

    go install github.com/RevylAI/greenlight/cmd/greenlight@latest

    Build from source

    git clone https://github.com/RevylAI/greenlight.git
cd greenlight && make build

    Note: The binary will be located at build/greenlight after building from source.

    # Homebrew (macOS)
brew install revylai/tap/greenlight

# Go install
go install github.com/RevylAI/greenlight/cmd/greenlight@latest

# Build from source
git clone https://github.com/RevylAI/greenlight.git
cd greenlight && make build

  9. Cut a new release of greenlight

    main

    To release a new version, you must first bump the version field in metadata.json and .claude-plugin/plugin.json via a standard Pull Request. Once the version is updated in those files, create and push a git tag following the vX.Y.Z format. Pushing the tag triggers a GitHub Action that builds binaries for macOS and Linux (amd64 and arm64) and publishes a GitHub release with checksums.

    Release Steps

    1. Update version in metadata.json and .claude-plugin/plugin.json.
    2. Create a tagged commit:
      git tag -a v0.2.0 -m "v0.2.0 — what changed"
git push origin v0.2.0
    git tag -a v0.2.0 -m "v0.2.0 — what changed"
git push origin v0.2.0

  10. Dry-run a release locally with GoReleaser

    main

    Before pushing a tag, you can validate your configuration and perform a local build using GoReleaser to ensure everything is correct. Note that local builds are not byte-reproducible; do not use hashes from local builds for Homebrew casks, as they will fail checksum verification against the official release artifacts.

    Use the following commands to validate and build locally:

    • goreleaser check: Validates the .goreleaser.yml configuration.
    • goreleaser release --snapshot --clean: Builds binaries into the ./dist directory without publishing anything.
    goreleaser check                        # validate the config
goreleaser release --snapshot --clean   # builds into ./dist, publishes nothing

  11. Install greenlight via Homebrew or Go

    main

    After a new release is published, you can install greenlight using either Homebrew or Go.

    Homebrew (macOS):

    brew install revylai/tap/greenlight

    Go:

    go install github.com/RevylAI/greenlight/cmd/greenlight@latest
    brew install revylai/tap/greenlight
go install github.com/RevylAI/greenlight/cmd/greenlight@latest

  12. Run App Store Preflight Compliance Scan

    main

    Use the preflight command to scan a project for App Store rejection risks, privacy compliance, and guideline violations. Run this at the project root.

    To scan the current directory:

    greenlight preflight .

    To include an IPA for binary analysis:

    greenlight preflight . --ipa /path/to/build.ipa

    Workflow for Compliance

    1. Run Scan: Execute greenlight preflight ..
    2. Triage: Review findings by severity: CRITICAL (must fix), WARN (high risk), and INFO (best practices).
    3. Fix: Apply code or configuration changes to address findings.
    4. Repeat: Re-run the scan until the output reports GREENLIT (zero CRITICAL findings).
    greenlight preflight .

# With an IPA
greenlight preflight . --ipa /path/to/build.ipa