gitshop

README

GitShop 🛍️

Sell from the place you already work: GitHub.

GitShop turns any GitHub repository into a transparent storefront. Customers place orders through GitHub Issues, pay with Stripe Checkout, and sellers manage setup and fulfillment from one GitShop admin dashboard.

See it live: gitcoffee, the first working shop built on GitShop.

Quick Start • How It Works • Local Development • Need Help • Admin Login

What Is GitShop? ✨

GitShop is for creators and teams who want a lightweight, GitHub-native way to sell products without running a separate ecommerce site.

• Product catalog in gitshop.yaml
• Order forms in GitHub issue templates
• Order status tracked with GitHub labels
• Payments and payouts through Stripe
• Seller operations managed in the GitShop admin dashboard

Quick Start 🚀

1. Choose your storefront repository. You can turn any GitHub repo into a shop, but the most straightforward setup is a dedicated repo for selling.
2. In that repo, use README.md as your storefront page with shop details, product information, and photos.
3. Install the GitShop GitHub App on your repository.
4. Sign in to GitShop with GitHub.
5. Select your repository/shop.
6. Complete the setup checklist in the dashboard.

How It Works 🔄

1. Define your catalog in gitshop.yaml.
2. Document your products in the repo README.md (descriptions, pricing context, photos, and your order link).
3. Create an issue template in .github/ISSUE_TEMPLATE/*.yaml with the marker # gitshop:order-template and label gitshop:order.
4. A customer discovers products in your README.md, then opens your repo's New issue page (or a direct issues/new?template=... link) and submits the order template.
5. GitShop validates the order and posts a Stripe Checkout link.
6. After payment, GitShop updates order labels and removes the checkout-link comment.
7. You manage shipping and delivery from the admin dashboard.

gitshop.yaml Example 🧾

shop:
  name: "My Shop"
  currency: "usd"
  manager: "octocat"
  shipping:
    flat_rate_cents: 500
    carrier: "USPS Priority"

products:
  - sku: "TSHIRT_BLACK_V1"
    name: "T-Shirt"
    description: "Black logo tee"
    unit_price_cents: 2500
    active: true
    options:
      - name: "size"
        label: "Size"
        type: "dropdown"
        required: true
        values: ["S", "M", "L", "XL"]

Current Limitations ⚠️

• USD only
• US shipping only
• Flat-rate shipping only
• One product SKU per order issue
• Refunds are handled in Stripe (not GitShop)
• Products are managed manually in gitshop.yaml
• If products need different option schemas, use separate order templates

Need Help? 🤝

• Issues: https://github.com/gitshopapp/gitshop/issues

Local Development 🛠️

1. Copy .env.example to .env and fill required values.
2. Start local services:

make docker.dev-setup
make docker.up

1. Stop services:

make docker.down

Common commands:

# Local host commands
make test
make lint
make build

# Docker workflow commands
make docker.test
make docker.lint
make docker.sqlc
make docker.templ
make docker.ui.build
make docker.build

Architecture Quick Map 🧭

• cmd/server/main.go: entrypoint
• app/: application wiring
• internal/handlers: HTTP and webhook transport
• internal/services: business logic
• internal/db: persistence layer
• internal/models: domain models
• ui/: templ views/components/assets

For full project conventions, workflows, and architecture details, see AGENTS.md.