JFrog Distribution

API transport: Prefer jf api (JFrog CLI 2.100.0+). See jf-api-patterns.md (path-only URLs; auth from jf config). Examples using curl with $JFROG_URL + bearer token are fallback when the CLI is missing or below 2.100.0.

JFrog Distribution Skill

Authentication

All requests require an access token via the Authorization header:

Authorization: Bearer $JFROG_ACCESS_TOKEN

Base URLs:

• Release Lifecycle: https://$JFROG_URL/lifecycle/api/...
• Distribution: https://$JFROG_URL/distribution/api/...
• Evidence: https://$JFROG_URL/evidence/api/...

When authentication is needed, follow the login-flow.md procedure to resolve the active JFrog environment. The jf CLI is required and will be installed automatically if missing. The agent checks saved credentials via jf config show and asks which environment to use if multiple are saved. If none exist, the agent drives the web login flow and saves credentials via jf config add.

Pre-flight: Before operations, verify the Lifecycle service is available: GET $JFROG_URL/lifecycle/api/v2/promotion/records?limit=1 (expect HTTP 200). If unavailable, inform the user that Release Lifecycle Management is not deployed on this instance and stop.

Core Concepts

Release Lifecycle Workflow

Build artifacts → Create Release Bundle → Promote DEV → STAGING → PROD → Distribute to Edge

Create Release Bundle

# From build info
curl -X POST -H "Authorization: Bearer $JFROG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "release_bundle_name": "my-app-release",
    "release_bundle_version": "1.0.0",
    "skip_docker_manifest_resolution": false,
    "source_type": "builds",
    "source": {
      "builds": [{"build_name": "my-app", "build_number": "42"}]
    }
  }' \
  "$JFROG_URL/lifecycle/api/v2/release_bundle"

# From file specs (artifacts)
curl -X POST -H "Authorization: Bearer $JFROG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "release_bundle_name": "my-release",
    "release_bundle_version": "2.0.0",
    "source_type": "file_specs",
    "source": {
      "file_specs": [
        {"pattern": "libs-release-local/com/example/app/2.0/*"}
      ]
    }
  }' \
  "$JFROG_URL/lifecycle/api/v2/release_bundle"

Promote Release Bundle

curl -X POST -H "Authorization: Bearer $JFROG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "STAGING",
    "included_repository_keys": ["libs-release-local"],
    "overwrite_existing_artifacts": false
  }' \
  "$JFROG_URL/lifecycle/api/v2/release_bundle/records/my-app-release/1.0.0/promote"

Distribute Release Bundle

curl -X POST -H "Authorization: Bearer $JFROG_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_create_missing_repositories": true,
    "distribution_rules": [
      {"site_name": "edge-us-east"},
      {"site_name": "edge-eu-west"}
    ]
  }' \
  "$JFROG_URL/distribution/api/v1/distribution/my-app-release/1.0.0"

Get Release Bundle Status

curl -H "Authorization: Bearer $JFROG_ACCESS_TOKEN" \
  "$JFROG_URL/lifecycle/api/v2/release_bundle/records/my-app-release/1.0.0"

Evidence Service

Evidence provides signed attestation metadata for artifacts, builds, and release bundles. Uses the DSSE (Dead Simple Signing Envelope) standard.

CLI Approach (Recommended)

# Attach evidence to a package
echo '{"actor":"ci-bot","date":"2024-01-15T10:00:00Z"}' > predicate.json
jf evd create \
  --package-name my-app --package-version 1.0 --package-repo-name docker-local \
  --key "$PRIVATE_KEY" \
  --predicate ./predicate.json \
  --predicate-type https://jfrog.com/evidence/signature/v1

# Attach evidence to an artifact
jf evd create \
  --subject-repo-path generic-local/readme/1.0/README.md \
  --key "$PRIVATE_KEY" \
  --predicate ./predicate.json \
  --predicate-type https://jfrog.com/evidence/signature/v1

# Attach evidence to a build
jf evd create \
  --build-name my-app --build-number 42 \
  --key "$PRIVATE_KEY" \
  --predicate ./predicate.json \
  --predicate-type https://jfrog.com/evidence/build-signature/v1

# Attach evidence to a release bundle
jf evd create \
  --release-bundle my-app-release --release-bundle-version 1.0.0 \
  --key "$PRIVATE_KEY" \
  --predicate ./predicate.json \
  --predicate-type https://jfrog.com/evidence/rbv2-signature/v1

REST API Approach

Two-step workflow (alternative to CLI when integrating third-party tools):

1. Prepare Evidence: POST /evidence/api/v1/evidence/prepare -- creates DSSE payload
2. Deploy Evidence: deploys the signed envelope to Artifactory

Since 7.129.1. Requires Enterprise+ license. Docs: https://jfrog.com/help/r/jfrog-artifactory-documentation/create-evidence-using-rest-apis

Reference Files

• api-reference.md -- Complete REST API endpoint catalog

Related Patterns

• release-lifecycle-management-without-security-gates [SIMPLE]
• release-lifecycle-with-security-gates [INTERMEDIATE]
• release-lifecycle-management-with-build-integration-security-gates-and-distribution [ADVANCED]
• release-lifecycle-with-evidence [ADVANCED]

After completing an action, check the Release Lifecycle Actions and Distribution Actions sections of skills/jfrog-patterns/flow-suggestions.md for flow context and offer the next step.

Official Documentation

• Release Lifecycle Management
• Distribution REST APIs
• Evidence Management
• Evidence REST API
• Evidence Examples

Related skills

For creating evidence-based promotion policies (lifecycle policies that gate on evidence), see compliance-and-policies.