Cargo Registry Guide

Artifact Keeper provides a Cargo-compatible registry using the sparse registry protocol for hosting Rust crates.

Endpoint

Cargo operations use the /cargo endpoint:

http://localhost:8080/cargo

This implements the Cargo sparse registry protocol.

Configuration

.cargo/config.toml

Configure Cargo to use Artifact Keeper by creating or editing .cargo/config.toml in your project or home directory (~/.cargo/config.toml):

[registries.artifact-keeper]
index = "sparse+http://localhost:8080/cargo/"

[registry]
default = "artifact-keeper"

Or configure without making it the default:

[registries.artifact-keeper]
index = "sparse+http://localhost:8080/cargo/"

Authentication

Add credentials to ~/.cargo/credentials.toml:

[registries.artifact-keeper]
token = "your-auth-token"

Or use environment variable:

export CARGO_REGISTRIES_ARTIFACT_KEEPER_TOKEN="your-auth-token"

Publishing Crates

Prepare Your Crate

Ensure Cargo.toml has proper metadata:

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <you@example.com>"]
description = "A short description of your crate"
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/my-crate"
readme = "README.md"
keywords = ["keyword1", "keyword2"]
categories = ["category1"]

[dependencies]
serde = "1.0"

Publish to Registry

cargo publish --registry artifact-keeper

If artifact-keeper is your default registry:

cargo publish

Dry Run

Test publishing without uploading:

cargo publish --registry artifact-keeper --dry-run

Publish Specific Package

For workspaces with multiple crates:

cargo publish --package my-crate --registry artifact-keeper

Installing Crates

Add Dependency

Add to your Cargo.toml:

[dependencies]
my-crate = "0.1.0"

If not using artifact-keeper as default registry:

[dependencies]
my-crate = { version = "0.1.0", registry = "artifact-keeper" }

Install Binary Crate

cargo install my-crate --registry artifact-keeper

Install Specific Version

[dependencies]
my-crate = "=0.1.0"  # Exact version
my-crate = "^0.1.0"  # Compatible version (default)
my-crate = "~0.1.0"  # Patch-level updates only

Version Management

Semantic Versioning

Cargo uses semantic versioning:

[package]
version = "1.2.3"
# Major.Minor.Patch

Update Version

Edit Cargo.toml and increment version:

version = "0.2.0"

Then publish:

cargo publish --registry artifact-keeper

Pre-release Versions

version = "1.0.0-alpha.1"
version = "1.0.0-beta.1"
version = "1.0.0-rc.1"

Yanking Versions

Yank a published version (marks as discouraged but doesn’t delete):

cargo yank --vers 0.1.0 --registry artifact-keeper

Un-yank a version:

cargo yank --vers 0.1.0 --undo --registry artifact-keeper

Multiple Registries

Configure Multiple Registries

[registries.artifact-keeper]
index = "sparse+http://localhost:8080/cargo/"

[registries.company-internal]
index = "sparse+http://internal-registry:8080/cargo/"

[registries.crates-io]
index = "https://github.com/rust-lang/crates.io-index"

Use Specific Registry

[dependencies]
public-crate = "1.0"  # From default registry
my-crate = { version = "0.1", registry = "artifact-keeper" }
internal-lib = { version = "2.0", registry = "company-internal" }

Set Default Registry

[registry]
default = "artifact-keeper"

Workspace Publishing

For multi-crate workspaces:

Workspace Cargo.toml

[workspace]
members = ["crate-a", "crate-b", "crate-c"]

[workspace.package]
version = "0.1.0"
edition = "2021"
authors = ["Your Name <you@example.com>"]
license = "MIT OR Apache-2.0"

Member Crate Configuration

[package]
name = "crate-a"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true

[dependencies]
crate-b = { version = "0.1", path = "../crate-b" }

Publish Workspace Crates

# Publish in dependency order
cargo publish --package crate-b --registry artifact-keeper
cargo publish --package crate-a --registry artifact-keeper

Features and Dependencies

Optional Features

[package]
name = "my-crate"
version = "0.1.0"

[features]
default = ["feature-a"]
feature-a = []
feature-b = ["dep:optional-dep"]
all = ["feature-a", "feature-b"]

[dependencies]
required-dep = "1.0"

[dependencies.optional-dep]
version = "2.0"
optional = true

Use Features

[dependencies]
my-crate = { version = "0.1", registry = "artifact-keeper", features = ["feature-b"] }

Integration with CI/CD

GitHub Actions

name: Publish Crate
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - name: Publish to Artifact Keeper
        env:
          CARGO_REGISTRIES_ARTIFACT_KEEPER_TOKEN: ${{ secrets.CARGO_TOKEN }}
        run: |
          cargo publish --registry artifact-keeper

GitLab CI

publish:
  image: rust:latest
  stage: deploy
  script:
    - echo "[registries.artifact-keeper]" > ~/.cargo/credentials.toml
    - echo "token = \"$CARGO_TOKEN\"" >> ~/.cargo/credentials.toml
    - cargo publish --registry artifact-keeper
  only:
    - tags

Jenkins Pipeline

pipeline {
    agent any

    tools {
        rust 'Rust 1.75'
    }

    stages {
        stage('Publish') {
            steps {
                withCredentials([
                    string(credentialsId: 'cargo-token', variable: 'CARGO_TOKEN')
                ]) {
                    sh '''
                        mkdir -p ~/.cargo
                        echo "[registries.artifact-keeper]" > ~/.cargo/credentials.toml
                        echo "token = \\"${CARGO_TOKEN}\\"" >> ~/.cargo/credentials.toml
                        cargo publish --registry artifact-keeper
                    '''
                }
            }
        }
    }
}

Package Contents

Include/Exclude Files

Control which files are included in the published package:

[package]
include = [
    "src/**/*",
    "Cargo.toml",
    "README.md",
    "LICENSE-*",
]

# Or use exclude
exclude = [
    ".github/*",
    "tests/*",
    "benches/*",
    "examples/*",
]

Package Verification

Check what will be published:

cargo package --list --registry artifact-keeper

Extract and inspect the package:

cargo package --registry artifact-keeper
tar -xzf target/package/my-crate-0.1.0.crate -C /tmp
ls -la /tmp/my-crate-0.1.0

Advanced Configuration

HTTP vs HTTPS

For HTTPS registries:

[registries.artifact-keeper]
index = "sparse+https://registry.example.com/cargo/"

Custom HTTP Headers

[http]
user-agent = "my-custom-agent"

Proxy Configuration

[http]
proxy = "http://proxy.example.com:8080"

Offline Mode

Build without network access (uses cached registry):

cargo build --offline

Troubleshooting

Authentication Failures

Verify token is correct:

cat ~/.cargo/credentials.toml

Test registry access:

cargo search my-crate --registry artifact-keeper

Publishing Errors

Enable verbose output:

cargo publish --registry artifact-keeper --verbose

Check package contents:

cargo package --list

Dependency Resolution Issues

Update registry index:

cargo update

Clean build cache:

cargo clean

Registry Index Issues

For sparse registries, clear HTTP cache:

rm -rf ~/.cargo/registry/cache/*

Best Practices

Crate Metadata

Include comprehensive metadata:

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"
authors = ["Your Name <you@example.com>"]
description = "A clear, concise description"
documentation = "https://docs.rs/my-crate"
homepage = "https://github.com/yourusername/my-crate"
repository = "https://github.com/yourusername/my-crate"
readme = "README.md"
license = "MIT OR Apache-2.0"
keywords = ["keyword1", "keyword2", "keyword3"]
categories = ["development-tools"]

README

Include a comprehensive README.md:

# My Crate

Brief description.

## Installation

\`\`\`toml
[dependencies]
my-crate = "0.1"
\`\`\`

## Usage

\`\`\`rust
use my_crate::function;

fn main() {
    function();
}
\`\`\`

Versioning Strategy

Patch (0.1.x): Bug fixes
Minor (0.x.0): New features, backward compatible
Major (x.0.0): Breaking changes

Testing Before Publishing

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Run clippy
cargo clippy -- -D warnings

# Build documentation
cargo doc --no-deps

# Verify package
cargo package --list