# GitHub Action Reference

The repository root provides a composite GitHub Action for downstream
distribution repositories.

The action downloads the configured conda-ship release assets for the current
runner, verifies their GitHub artifact attestations and `SHA256SUMS`, and runs
the downloaded `cs` binary to preflight and build a runtime. The preflight uses
`cs build --dry-run`, then the action runs the real build. It does not build
conda-ship from source.
Self-hosted runners must provide the GitHub CLI because attestation
verification uses `gh attestation verify`.

The action builds only from committed project input. The selected root must
contain a supported {doc}`manifest and lockfile pair <configuration>`.
When the manifest or matching lockfile is missing, the action fails instead of
generating or solving project configuration in CI. The example below requires
`runtime-name`, `delegate-executable`, `source-environment`, and a runtime
version in the manifest. See {doc}`configuration` for supported version sources.

When the selected conda-ship config sets
`runtime-version = { from = "project-metadata" }`, the action first lets
`cs build --dry-run` report that project metadata resolution is required. It
then sets up Python with `actions/setup-python`, resolves the downstream
project version through `pypa/build`, and retries the build with an explicit
`--runtime-version`. Static runtime versions and explicit `runtime-version`
inputs do not set up Python.

```yaml
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- uses: conda-incubator/conda-ship@FULL_RELEASE_COMMIT_SHA # X.Y.Z
  id: cs
  with:
    conda-ship-version: "X.Y.Z"
```

## Inputs

`conda-ship-version`
: conda-ship release version to download, such as `X.Y.Z`. Set this when the
  action source is pinned by full commit SHA. When omitted, the action uses the
  exact action tag if available.

`runtime-name`
: Override `[tool.conda-ship].runtime-name` for this build.

`artifact-name`
: Staged executable and artifact stem override. Set this when any layout should
  stage a different command and release artifact name than `runtime-name`, such
  as `cxz` for a distribution whose base runtime name is `cx`. When omitted,
  the manifest's `artifact-name` is used if set, otherwise the runtime name.

`delegate-executable`
: Override `[tool.conda-ship].delegate-executable` for this build.

`runtime-version`
: Override the runtime version for this build, including a version configured
  in the manifest or resolved from project metadata.

`python-version`
: Python version used only when the action must resolve
  `runtime-version = { from = "project-metadata" }`. Defaults to `3.12`.

`root`
: Project root containing `conda.toml`/`conda.lock`, `pixi.toml`/`pixi.lock`,
  or `pyproject.toml` with a nonempty `[tool.conda.workspace]` and `conda.lock`,
  or a nonempty `[tool.pixi.workspace]` and `pixi.lock`.
  Defaults to the workflow workspace.

`artifact-layout`
: Artifact layout to build. Supported values are `online`, `external`, and
  `embedded`. Overrides `[tool.conda-ship].artifact-layout` when set. Otherwise
  the action leaves layout selection to the manifest and `cs` defaults to
  `online`. External artifacts stage the runtime and bundle as separate files.
  Embedded artifacts carry package archives inside the runtime.

`docs-url`
: Documentation URL stamped into generated runtime metadata. Must start
  with `https://` or `http://` and must not contain whitespace or control
  characters.

`install-scheme`
: Install scheme stamped into the generated runtime. Supported values are
  `conda-home` and `user-data`.

`install-name`
: Directory name for this runtime's managed base prefix under the install
  scheme. When omitted, `cs` uses `[tool.conda-ship].install-name` or the
  resolved runtime name.

`installer`
: Package manager or installer stamped into runtime metadata.

The action does not duplicate `cs build` validation in shell. It passes
non-empty inputs to `cs build --dry-run` and then to `cs build`. Invalid values
fail in the builder.

## Supported Runner Platforms

The action selects `cs-<target>` and `cs-template-<target>` from the current
runner's operating system and architecture:

| Runner OS | Runner arch | Target | Support status |
| --- | --- | --- | --- |
| `Linux` | `X64` | `x86_64-unknown-linux-gnu` | End-to-end runtime bootstrap covered. |
| `Linux` | `ARM64` | `aarch64-unknown-linux-gnu` | End-to-end runtime bootstrap covered. |
| `macOS` | `X64` | `x86_64-apple-darwin` | End-to-end runtime bootstrap covered. |
| `macOS` | `ARM64` | `aarch64-apple-darwin` | End-to-end runtime bootstrap covered. |
| `Windows` | `X64` | `x86_64-pc-windows-msvc` | End-to-end runtime bootstrap covered. |
| `Windows` | `ARM64` | `aarch64-pc-windows-msvc` | Builder assets, template assets, PyPI wheels, action target mapping, and native structural runtime stamping are covered. Full runtime bootstrap is not end-to-end supported yet. |

Use GitHub-hosted or self-hosted runners that report one of those
`runner.os`/`runner.arch` combinations. Release workflows should pin the action
source by full commit SHA and pass the matching conda-ship release through the
`conda-ship-version` input.

## Outputs

`cs-path`
: Absolute path to the downloaded and verified `cs` builder. Use this after
  downstream signing or other finalization to run `cs package-update` with the
  action's `info-path` and finalized executable. The action does not generate
  or upload an update package itself.

`dist-path`
: Absolute path to the directory containing all generated runtime artifacts.
  Use this for artifact uploads when the complete build output should be
  published together.

`binary-path`
: Absolute path to the generated runtime.

`asset-name`
: Platform-qualified asset filename.

`info-path`
: Absolute path to the artifact info JSON.

`lock-path`
: Absolute path to the staged runtime lock.

`package-list-path`
: Absolute path to the staged package list.

`sbom-path`
: Absolute path to the CycloneDX 1.7 SBOM.

`checksums-path`
: Absolute path to the SHA256 checksum file.

`bundle-path`
: Absolute path to the external bundle when `artifact-layout: external`. Empty
  for `online` and `embedded`.