FabricGate

Discover, pull and verify FPGA designs for your board — one command, any runtime.

FabricGate is a package registry for FPGA designs (bitstreams plus the metadata a runtime needs to load them). This repository contains the client side: the fabricgate CLI, the Python SDK, the shared data models, and the public API contracts. The hosted registry lives at https://registry.fabricgate.dev.

Status: alpha (0.1.0). The registry is being seeded with community PYNQ overlays. Interfaces marked stable in docs/specs/ are kept backward compatible; everything else may still change before 1.0.

Install

pip install fabricgate

Python 3.11 or newer. fgate is installed as a short alias of fabricgate.

Three steps to a running design

# 1. Find a design for your board
fabricgate search --platform pynq-z2/pynq adder

# 2. Pull it (bitstream + hwh + manifest, digests verified on download)
fabricgate pull example/adder-demo:1.0.0 --platform pynq-z2/pynq

# 3. Load it with the runtime you already use
python -c "from pynq import Overlay; ol = Overlay('adder-demo/adder.bit')"

example/adder-demo is a placeholder name; run fabricgate search to see what is actually published. The --platform value is <board>/<runtime>; run fabricgate pull --help for the resolution rules, including the generic-<device> fallback.

What the CLI can do

fabricgate --json gives machine-readable output for every command.

Publishing from CI

Create an API key once with an interactive login, then hand it to CI in FABRICGATE_TOKEN. When the variable is set (and not empty), the commands that use credentials (push, yank, list --remote, quota and so on) send it instead of the credentials fabricgate login stored, and it never shows up in logs, --json output or error messages. search, info, stats, diff, watch and license-check use no credentials.

fabricgate login
fabricgate token create --name ci-pipeline --scopes ns:<your-namespace>:write --expires 90d

# .github/workflows/publish.yml
- run: pip install fabricgate
- run: fabricgate push ./my-design/
  env:
    FABRICGATE_TOKEN: ${{ secrets.FABRICGATE_TOKEN }}

An API key covers writes to its namespace (push, yank, deprecate); key management (fabricgate token) still needs fabricgate login. fabricgate webhook needs ns:<namespace>:admin, which an API key cannot carry, so the registry refuses a key there with 403 (the registry does not serve webhooks yet and answers 404 for now). Pass --namespace to list --remote and quota, since the CLI cannot tell a key's namespace. The --token flag is not implemented yet.

Supported boards and runtimes

The bundled Board DB (src/fabricgate/data/board-db/official.yaml) currently knows these boards:

Adding a board is a data change; see CONTRIBUTING.md.

SDK

from fabricgate.sdk import api

result = api.pull("example/adder-demo:1.0.0", platform="pynq-z2/pynq")
print(result.artifacts)

The SDK wraps the same client the CLI uses. See docs/specs/client-behavior.md for the resolution and caching rules.

Public contracts

docs/contracts/ is the source of truth for the registry's public API:

• openapi.yaml / openapi.json — Registry HTTP API
• schemas/design-index.schema.json, schemas/platform-manifest.schema.json, schemas/board-db.schema.json — wire formats
• CHANGELOG.md — contract changes and migration notes

Specifications for the CLI, client behaviour and data formats are in docs/specs/.

Self-hosting and the registry implementation

The registry server is operated as a hosted service and its implementation is not published at this stage (see docs/specs/ for the distribution policy summary in client-behavior.md). Everything a client needs to interoperate — API, schemas, error formats — is in this repository, so alternative implementations are possible.

Contributing, security, license

• CONTRIBUTING.md — development setup, tests, pull requests
• SECURITY.md — how to report a vulnerability
• LICENSE — MIT

Verifying what you install

Every release is published from this repository via PyPI Trusted Publishing and carries a GitHub build-provenance attestation:

pip download --no-deps fabricgate==0.1.0
gh attestation verify fabricgate-0.1.0-py3-none-any.whl --repo harurun78/fabricgate