> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/deployment-and-infrastructure/release-signing.md).

# Release Signing & Verification

> **Audience:** Users, operators, and security auditors who need to verify the integrity of EDDI releases.

## What Is Signed?

EDDI's primary release artifacts are **Docker images** published to [Docker Hub: `labsai/eddi`](https://hub.docker.com/r/labsai/eddi). Starting with v6.0.0, every image pushed by the CI/CD pipeline is **cryptographically signed** using [Sigstore cosign](https://github.com/sigstore/cosign) with keyless OIDC signing.

This includes all images pushed after signing was enabled:

* Every build pushed from `main` (e.g., `labsai/eddi:6.0.0-b42`)
* Every release candidate (e.g., `labsai/eddi:6.0.0-RC2`)
* Every general availability release (e.g., `labsai/eddi:6.6.0`)
* The `latest`, major and minor aliases (moved only by a stable `MAJOR.MINOR.PATCH` tag, never by a release candidate)

The signature is made on the pushed image's **digest**, not on a tag, so it stays bound to the exact bytes CI tested; `cosign verify …:<tag>` resolves the tag to its digest and checks that. Each pushed image also gets a **SLSA build-provenance attestation** (`actions/attest-build-provenance`, pushed to the registry), and each GitHub release carries a `SHA256SUMS` of the files the installers download (the compose files, the Keycloak realm and theme, the monitoring assets) with a keyless cosign bundle, `SHA256SUMS.sigstore.json`.

> **Note:** Images published before v6.0.0 are not signed. Signature verification only applies to images built after this feature was enabled.

***

## How Signing Works

EDDI uses **keyless signing** — there are no long-lived private keys to manage or protect:

1. The GitHub Actions CI pipeline builds and pushes the Docker image
2. GitHub provides an **OIDC identity token** proving the workflow identity
3. **Fulcio** (Sigstore's certificate authority) issues a short-lived certificate based on that identity
4. **cosign** signs the image using the ephemeral certificate
5. The signature is stored as an **OCI artifact** alongside the image in Docker Hub
6. The signing event is recorded in the **Rekor** public transparency log

```
GitHub Actions OIDC Token
        │
        ▼
   ┌─────────┐     ┌────────────┐
   │  Fulcio  │────▶│  Ephemeral │
   │   (CA)   │     │   Cert     │
   └─────────┘     └─────┬──────┘
                         │
                         ▼
                  ┌──────────────┐
                  │  cosign sign │──▶ Signature stored in Docker Hub
                  └──────┬───────┘
                         │
                         ▼
                  ┌──────────────┐
                  │    Rekor     │──▶ Transparency log entry
                  │  (public)    │
                  └──────────────┘
```

### Security Properties

| Property                                 | How it's achieved                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------- |
| **No private key exposure**              | Ephemeral keys exist only in runner memory for milliseconds — never stored anywhere   |
| **Tamper evidence**                      | Signatures are recorded in the immutable Rekor transparency log                       |
| **Identity binding**                     | The signature proves the image was built by the `labsai/EDDI` GitHub Actions workflow |
| **Private key not on distribution site** | Docker Hub only stores the signature and public certificate, never a private key      |

***

## How to Verify

### Prerequisites

Install cosign:

```bash
# macOS
brew install cosign

# Linux (download binary)
curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
chmod +x cosign-linux-amd64
sudo mv cosign-linux-amd64 /usr/local/bin/cosign

# Or download from https://github.com/sigstore/cosign/releases
```

### Verify an Image

```bash
cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "^https://github\.com/labsai/EDDI/\.github/workflows/ci\.yml@refs/(heads/main|tags/[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$" \
  labsai/eddi:6.6.0
```

Replace the tag with any tag you want to verify (`latest`, a release candidate such as `6.0.0-RC2`, a build such as `6.0.0-b42`, etc.).

**Successful output** will show the verified certificate chain and Rekor log entry:

```
Verification for docker.io/labsai/eddi:6.6.0 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - The code-signing certificate was verified using trusted certificate authority
```

### Verify by Digest (Recommended)

For maximum security, verify by image digest instead of tag:

```bash
# Get the digest
docker pull labsai/eddi:6.6.0
DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' labsai/eddi:6.6.0)

# Verify the digest
cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "^https://github\.com/labsai/EDDI/\.github/workflows/ci\.yml@refs/(heads/main|tags/[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$" \
  $DIGEST
```

### Inspect the Transparency Log

Every signature is publicly recorded in [Rekor](https://rekor.sigstore.dev/). When you run `cosign verify`, the output includes the Rekor log index. You can also inspect the full transparency log entry for a signed image:

```bash
cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "^https://github\.com/labsai/EDDI/\.github/workflows/ci\.yml@refs/(heads/main|tags/[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$" \
  --output-text \
  labsai/eddi:6.6.0
```

This outputs the full certificate chain and Rekor log entry as JSON.

### Verify the Provenance and the Release Checksums

```bash
# How the image was built (this workflow, this commit, this runner)
gh attestation verify oci://docker.io/labsai/eddi:<tag> --repo labsai/EDDI

# The checksum list attached to a GitHub release, signed at that tag
gh release download <tag> --repo labsai/EDDI --pattern 'SHA256SUMS*'
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/labsai/EDDI/.github/workflows/ci.yml@refs/tags/<tag>" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS
gh attestation verify SHA256SUMS --repo labsai/EDDI
```

`install.sh` and `install.ps1` check the files they download against that `SHA256SUMS`, and verify its bundle against the same identity when cosign is installed.

***

## Git Tag Signing

Git tags are **not** signed today: the published release tags are lightweight or unsigned annotated tags, so `git tag -v` has nothing to verify on them. The image signature, the provenance attestation and the signed `SHA256SUMS` above are the release's integrity guarantees. A maintainer who wants to add a signed tag on top creates it with a GPG or SSH key:

```bash
# Create a signed tag
git tag -s 6.3.0 -m "Release 6.3.0"
git push origin 6.3.0

# Verify a signed tag
git tag -v 6.3.0
```

> **Release tags carry no `v` prefix.** `ci.yml` triggers on `tags: ["[0-9]*"]`, so `v6.3.0` matches nothing and silently runs no workflow — no build, no image, and none of the signing or attestation described on this page. Signing the tag does not change that; a signed `v6.3.0` is just as inert. See [Release & Versioning Strategy](https://docs.labs.ai/deployment-and-infrastructure/release-versioning.md#version-format).
>
> **Note:** The primary release integrity guarantee is provided by the Docker image signing described above. A signed Git tag would add assurance that the tag was created by an authorized maintainer.

***

## Related Documentation

* [Release & Versioning Strategy](https://docs.labs.ai/deployment-and-infrastructure/release-versioning.md) — Docker tags, branching model, how to release
* [Security Policy](https://github.com/labsai/EDDI/tree/main/SECURITY.md) — Vulnerability reporting, scope, security practices
* [CI/CD Pipeline](https://github.com/labsai/EDDI/tree/main/.github/workflows/ci.yml) — The signing implementation
