Contributing Guide - App Store Connect CLI

Thanks for your interest in contributing to the App Store Connect CLI! This guide will help you get started with development, testing, and submitting contributions.

Development Setup

Requirements

Go 1.26 or higher
Git
(Optional) macOS for keychain integration testing

Clone and Build

Clone the repository and build the CLI:

git clone https://github.com/rudrankriyam/App-Store-Connect-CLI.git
cd App-Store-Connect-CLI
make build

This creates the asc binary in the current directory.

Run Tests

Run the test suite:

go test ./...

Important: Always use keychain bypass when running tests to avoid macOS keychain prompts:

ASC_BYPASS_KEYCHAIN=1 make test

Optional Tooling

Install development tools:

make tools   # Installs gofumpt + golangci-lint
make lint    # Uses golangci-lint if installed, else go vet
make format  # gofmt + gofumpt (requires gofumpt)

Integration Tests (Opt-in)

Integration tests hit the real App Store Connect API and are skipped by default. To run integration tests, set credentials in your environment:

export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"
export ASC_APP_ID="YOUR_APP_ID"

make test-integration

Headless Alternative

For CI/CD or headless environments, use base64-encoded keys:

export ASC_PRIVATE_KEY_B64="BASE64_ENCODED_KEY"

Local API Testing (Optional)

If you have App Store Connect API credentials, you can run real API calls locally:

export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"
export ASC_APP_ID="YOUR_APP_ID"

asc feedback --app "$ASC_APP_ID"
asc crashes --app "$ASC_APP_ID"
asc reviews --app "$ASC_APP_ID"

Credential Storage

Credentials are stored:

macOS: System keychain (when available)
Fallback: Config file at ~/.asc/config.json (restricted permissions)
Repo-local: ./.asc/config.json (also supported)

Important: Do not commit secrets or .p8 files to the repository.

Local Validation

Run this checklist before opening a PR:

make tools               # Install gofumpt + golangci-lint
make format              # Format code
make lint                # Lint code
make check-command-docs  # Verify command docs are up to date
ASC_BYPASS_KEYCHAIN=1 make test  # Run tests (bypasses keychain)
make build               # Build binary
./asc --help             # Smoke-test the binary

Command Documentation

If you changed command/help text, regenerate documentation:

make generate-command-docs  # Updates docs/COMMANDS.md
make check-command-docs     # Verifies docs are current

Commit docs/COMMANDS.md if it changed.

Pull Request Guidelines

Before Opening a PR

Keep PRs small and focused: One logical change per PR
Add or update tests: Cover new behavior and edge cases
Update README: If behavior or scope changes
Avoid committing credentials: No API keys or .p8 files
Run validation: Complete the local validation checklist above

PR Checklist

Code formatted (make format)
Linting passes (make lint)
Tests pass (ASC_BYPASS_KEYCHAIN=1 make test)
Command docs updated (make generate-command-docs)
Build succeeds (make build)
README updated (if needed)
No secrets committed

Pre-commit Hook

Install local pre-commit hook to enforce checks automatically:

make install-hooks

This runs formatting, linting, and doc checks before each commit.

PR Description

Include in your PR description:

What: What does this PR do?
Why: Why is this change needed?
How: How does it work?
Testing: Commands run and key scenarios validated
Breaking changes: Note any backward-incompatible changes

Development Workflow

Git Workflow

Fork the repository
Create a branch from main:
```
git checkout -b feature/my-feature
```

Make changes and commit:

git add .
git commit -m "feat: add new feature"

Push to your fork:
```
git push origin feature/my-feature
```
Open a PR against main

Commit Message Style

Follow conventional commit format:

feat: - New feature
fix: - Bug fix
refactor: - Code refactoring
test: - Test additions/changes
docs: - Documentation changes
chore: - Maintenance tasks

Example:

feat(builds): add PKG upload support

- Use com.apple.pkg UTI for PKG files
- Add validation for PKG file format
- Update upload timeout defaults

Testing Discipline

Test-Driven Development (TDD)

For bugs, refactors, and new features:

Start with a failing test that captures expected behavior
Implement the fix or feature
Verify the test passes
Refactor if needed

Test Coverage

For new features:

CLI-level tests: Flags, output, errors, exit codes
Unit tests: Core logic and edge cases
Integration tests (optional): Real API calls

Test Patterns

Test realistic CLI invocation patterns:

# Flags before subcommands
asc --output json builds list

# Flag values that look like subcommands
asc --report junit completion

# Multiple flags with values
asc -a val1 -b val2 subcmd

For more details, see docs/TESTING.md.

CLI Implementation Checklist

When adding new commands:

Register in internal/cli/registry/registry.go
Set UsageFunc: shared.DefaultUsageFunc
Use shared.ContextWithTimeout for HTTP requests
Validate required flags and test error messages
Add internal/cli/cmdtest coverage
Use httptest for network payload tests
Update help text and examples

Architecture Guidelines

Architecture-First Development

Before implementing new commands/flags, produce a design note:

Command placement in existing taxonomy
OpenAPI endpoint/schema validation
UX shape: Flags, output formats, exit codes
Backward compatibility and deprecation impact
Test plan: RED → GREEN approach

If command shape is ambiguous, align before coding.

Command Lifecycle

User-facing commands/flags follow lifecycle states:

experimental - Early development, may change
stable - Production-ready, backward compatible
deprecated - Scheduled for removal, migration path provided
removed - No longer available

Do not delete stable commands directly. Deprecate first with:

Warning text in help/output
Tests covering old and new behavior
Changelog entry with upgrade path

Security

Reporting Security Issues

Do NOT open public GitHub issues for security vulnerabilities. Report privately using GitHub Security Advisories: https://github.com/rudrankriyam/App-Store-Connect-CLI/security/advisories/new If you can’t use GitHub Security Advisories, contact the maintainer: https://github.com/rudrankriyam

What to Include

Clear description of vulnerability and potential impact
Steps to reproduce (proof-of-concept if possible)
Affected versions and platforms (macOS/Linux, Go version, etc.)

Supported Versions

Security updates are provided for:

Latest stable release
main branch

Wall of Apps

Wall content is generated by make update-wall-of-apps. The generator reads docs/wall-of-apps.json and updates the Wall snippet in README.md.

Add Your App

Fork the repository

Run:

make generate app APP="Your App Name" LINK="https://apps.apple.com/app/id1234567890" CREATOR="your-github-handle" PLATFORM="iOS,macOS"

This updates docs/wall-of-apps.json and syncs README.md in one step.

Alternative: Edit docs/wall-of-apps.json directly, then run:
```
make update-wall-of-apps
```
Commit all generated changes:
- docs/wall-of-apps.json
- README.md
Open a PR

Format

{
  "app": "Your App Name",
  "link": "https://apps.apple.com/app/id1234567890",
  "creator": "your-github-handle",
  "platform": ["iOS"]
}

Platform values are free-form labels: iOS, macOS, watchOS, tvOS, visionOS, Android, Web. Note: If you only change the Wall table in README.md without updating docs/wall-of-apps.json, CI will fail the Wall generation check.

Additional Resources

Documentation

docs/GO_STANDARDS.md - Go coding standards
docs/TESTING.md - Testing patterns and conventions
docs/CONTRIBUTING.md - Detailed CLI development notes
docs/API_NOTES.md - API quirks and behaviors
CONTRIBUTING.md - This guide (root)

API Reference

OpenAPI snapshot: docs/openapi/latest.json
Endpoint index: docs/openapi/paths.txt
API docs: https://sosumi.ai/documentation/appstoreconnectapi/

Getting Help

If you need help:

Check existing issues: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues
Read documentation: Command reference, API notes, testing guide
Ask in discussions: Open a GitHub discussion
Open an issue: If you’ve found a bug or have a feature request

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Code of Conduct

Please review and follow the Code of Conduct.

Thank You!

Contributions of all sizes are appreciated. Whether it’s fixing typos, reporting bugs, or implementing features, every contribution helps make the CLI better for everyone.

Additional Resources

​Development Setup

​Requirements

​Clone and Build

​Run Tests

​Optional Tooling

​Integration Tests (Opt-in)

​Headless Alternative

​Local API Testing (Optional)

​Credential Storage

​Local Validation

​Command Documentation

​Pull Request Guidelines

​Before Opening a PR

​PR Checklist

​Pre-commit Hook

​PR Description

​Development Workflow

​Git Workflow

​Commit Message Style

​Testing Discipline

​Test-Driven Development (TDD)

​Test Coverage

​Test Patterns

​CLI Implementation Checklist

​Architecture Guidelines

​Architecture-First Development

​Command Lifecycle

​Security

​Reporting Security Issues

​What to Include

​Supported Versions

​Wall of Apps

​Add Your App

​Format

​Additional Resources

​Documentation

​API Reference

​Getting Help

​License

​Code of Conduct

​Thank You!

Development Setup

Requirements

Clone and Build

Run Tests

Optional Tooling

Integration Tests (Opt-in)

Headless Alternative

Local API Testing (Optional)

Credential Storage

Local Validation

Command Documentation

Pull Request Guidelines

Before Opening a PR

PR Checklist

Pre-commit Hook

PR Description

Development Workflow

Git Workflow

Commit Message Style

Testing Discipline

Test-Driven Development (TDD)

Test Coverage

Test Patterns

CLI Implementation Checklist

Architecture Guidelines

Architecture-First Development

Command Lifecycle

Security

Reporting Security Issues

What to Include

Supported Versions

Wall of Apps

Add Your App

Format

Additional Resources

Documentation

API Reference

Getting Help

License

Code of Conduct

Thank You!