# Package & Publish with Biosimulant Use the canonical `biosimulant` CLI for local validation and release work, or connect the Biosimulant GitHub App for push-to-deploy publishing from a branch. ## GitHub App auto-deploy The hosted workflow is the simplest path for teams: 1. Install the Biosimulant GitHub App from the Deployments screen. 2. Select one repository, one branch, and the path to a lab manifest such as `labs/my-lab/lab.yaml`. 3. Link the source to an existing lab, or provide a package name when creating a new lab. 4. Push to that branch. Each push runs the same backend stages used by package upload: - clone repository archive - validate the selected `lab.yaml` - build one `.bsilab` archive from that lab folder - publish and materialize the Lab into the Package Registry Deployment history stays visible in the web app with stage-by-stage status, commit SHA, published lab rows, and failure reasons for validation, build, or publish issues. A single repository branch can deploy multiple labs by creating one source per lab manifest path. The GitHub App should be granted: - repository contents: read - metadata: read - commit statuses: write - webhooks for push events V1 GitHub auto-deploy publishes Labs only. Preview environments and smoke tests are not part of this flow yet. ## CLI workflow Use the CLI when you want to validate or publish locally, wire it into CI yourself, or test packages before enabling auto-deploy. For single-lab work, prefer the lab-centered flow: ```bash biosimulant auth login biosimulant labs init ./my-lab --name "My Lab" biosimulant labs add-model ./my-lab ./models/my-model --as model biosimulant labs validate ./my-lab biosimulant labs serve ./my-lab biosimulant labs run ./my-lab --results-file results.json --json biosimulant labs publish ./my-lab --visibility private ``` Biosimulant Hub is the default registry. To publish to another Registry API v1 service, authenticate to its origin and use a registry-qualified package reference: ```bash printf '%s\n' "$TOKEN" | \ biosimulant auth login registry.example.com --token-stdin biosimulant labs publish ./my-lab --json ``` Registry credentials are stored separately by origin. Never place a token in a package reference, command history, or lab manifest. ## Declare packages Create a `biosimulant-packages.yaml` at the repository root: ```yaml schema_version: "1" namespace: your-org default_visibility: public packages: - id: my-lab package: your-org/my-lab version: 1.0.0 type: lab path: labs/my-lab visibility: public ``` Each package entry points to a lab source tree containing `lab.yaml`. ## Validate ```bash biosimulant labs release validate biosimulant-packages.yaml ``` Validation checks package names, exact SemVer versions, source paths, manifests, dependency pins, embedded paths, and duplicate `package@version` entries. ## Build ```bash biosimulant labs release build biosimulant-packages.yaml --out dist/biosimulant-packages ``` The build creates `.bsilab` archives under the output directory. Each archive contains `package.yaml`, `payload/`, and `integrity/sha256sums.txt`. ## Publish Publish builds, validates, uploads each artifact, and writes `dist/package-report.json`: ```bash biosimulant labs release publish biosimulant-packages.yaml ``` Use `--dry-run` to validate and build locally without uploading: ```bash biosimulant labs release publish biosimulant-packages.yaml --dry-run ``` Publishing the same `package@version` with different content fails on the backend. Re-uploading the same content reuses the existing artifact. ## Pull and run versions Consumers can use exact package refs, or omit the version to resolve the latest accessible package: ```bash LAB_REF="your-org/my-lab@1.0.0" biosimulant labs search "my lab" biosimulant labs info "$LAB_REF" biosimulant labs pull "$LAB_REF" biosimulant labs run ./my-lab --results-file results.json --json ``` Exact package refs use `namespace/name@x.y.z`; `namespace/name` resolves latest for pull and run commands. ## Local CI ```bash biosimulant labs release ci biosimulant-packages.yaml biosimulant labs release ci biosimulant-packages.yaml --publish biosimulant labs release ci biosimulant-packages.yaml --publish --json ``` The same command can run locally first and later move into GitHub Actions. All package commands exit non-zero on validation, build, or upload failure. Use `--json` for one schema-v1 result or `--json-stream` for ordered progress followed by one terminal result. See [Machine-readable output](/references/cli/machine-output) for the envelope and exit-code contract. ## Compatibility Smoke Before publishing a model or lab that should also run through the open-source Python package flow, build and run the package locally: ```bash biosimulant labs package path/to/lab --out dist biosimulant labs validate dist/your-package.bsilab --json biosimulant labs run dist/your-package.bsilab --no-install-deps --json ``` This catches entrypoint loading, typed run input payloads, child-lab flattening, and `io.maps_to` remapping issues before the same package reaches Desktop or remote execution. GPU or otherwise heavy packages can keep full execution in remote smoke tests, but should still validate manifests and entrypoints locally. ## Next Steps - [Write a model.yaml](/how-to/library/write-model-manifest): manifest guide - [Use a BioModule](/how-to/library/use-biomodule): run packaged model code in local workflows - [CLI Command Reference](/references/cli/command-reference): full `biosimulant labs` command catalog