Blob Action

GitHub Action to install and use the blob CLI for OCI artifact management with signing and attestation support.

Table of Contents

• Features
• Usage
• Inputs
• Outputs
• Contributing
• License

Features

• Install and cache the blob CLI
• Push directories to OCI registries as blob archives
• Pull blob archives from OCI registries
• Verify archive signatures and policies
• Inspect archive metadata
• Sigstore keyless signing
• Cosign verification of CLI downloads

Usage

Install Only

- name: Install blob CLI
  uses: meigma/blob-action@v0
  with:
    action: install-only

Push with Signing

permissions:
  packages: write
  id-token: write  # Required for Sigstore keyless signing

steps:
  - uses: actions/checkout@v4

  - uses: docker/login-action@v3
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - name: Push archive
    id: push
    uses: meigma/blob-action@v0
    with:
      action: push
      ref: ghcr.io/${{ github.repository }}:${{ github.sha }}
      path: ./dist
      sign: true
      annotations: |
        org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
        org.opencontainers.image.revision=${{ github.sha }}

  - name: Generate attestation
    uses: actions/attest-build-provenance@v2
    with:
      subject-name: ghcr.io/${{ github.repository }}
      subject-digest: ${{ steps.push.outputs.digest }}
      push-to-registry: true

Pull with Verification

- name: Pull and verify
  uses: meigma/blob-action@v0
  with:
    action: pull
    ref: ghcr.io/org/repo@sha256:abc123...
    path: ./extracted
    policy: .github/policies/production.yaml

Verify Signatures and Attestations

Create a policy file (e.g., .github/policies/production.yaml):

signature:
  keyless:
    issuer: https://token.actions.githubusercontent.com
    identity: https://github.com/myorg/myrepo/.github/workflows/release.yml@refs/heads/main

provenance:
  slsa:
    repository: myorg/myrepo
    branch: main

Then verify the archive:

- name: Verify archive
  uses: meigma/blob-action@v0
  with:
    action: verify
    ref: ghcr.io/org/repo@sha256:abc123...
    policy: .github/policies/production.yaml

Inspect Archive

- name: Inspect archive
  id: inspect
  uses: meigma/blob-action@v0
  with:
    action: inspect
    ref: ghcr.io/org/repo:latest

- name: Use outputs
  run: |
    echo "Digest: ${{ steps.inspect.outputs.digest }}"
    echo "Files: ${{ steps.inspect.outputs.file-count }}"
    echo "Size: ${{ steps.inspect.outputs.total-size }}"

Custom Configuration

Configure the blob CLI with default policies, cache settings, and other options:

- name: Pull with custom config
  uses: meigma/blob-action@v0
  with:
    action: pull
    ref: ghcr.io/org/repo:latest
    config: |
      cache:
        enabled: true
        ref_ttl: 10m
      policies:
        - match: ghcr\.io/myorg/.*
          policy:
            signature:
              keyless:
                issuer: https://token.actions.githubusercontent.com
                identity: https://github.com/myorg/*

Inputs

Input	Description	Default
action	Operation: push, pull, verify, inspect, install-only	install-only
version	Blob CLI version to install	latest
ref	OCI reference (e.g., ghcr.io/org/repo:tag)	-
path	Source directory (push) or destination (pull)	.
sign	Sign manifest with Sigstore keyless signing	false
compression	Compression type: zstd, none	zstd
annotations	Manifest annotations (multiline key=value)	-
policy	Policy files for verification (one per line)	-
policy-rego	Path to OPA Rego policy file	-
no-default-policy	Skip policies from config file	false
skip-cache	Bypass registry caches for this operation	false
config	Blob CLI configuration file contents (YAML format)	-
verify-checksum	Verify CLI checksum signature with Cosign	true
github-token	GitHub token for API requests (avoids rate limits)	${{ github.token }}

Outputs

Output	Description
digest	Manifest digest (sha256:...)
version	Installed blob CLI version
file-count	Number of files in archive
total-size	Total archive size in bytes

Contributing

See CONTRIBUTING.md for development setup and guidelines.

For security issues, see SECURITY.md.

License

Dual-licensed under Apache 2.0 or MIT at your option.