Cloudflare::Artifacts

A Ruby client for the Cloudflare Artifacts REST API, built on Faraday.

Manage Artifacts repositories and tokens from Ruby — create, list, fork, import, and mint short-lived Git credentials.

Installation

Add to your Gemfile:

gem "cloudflare-artifacts"

Or install directly:

gem install cloudflare-artifacts

Usage

Configure once, use everywhere

require "cloudflare/artifacts"

Cloudflare::Artifacts.configure do |c|
  c.account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID")
  c.api_token  = ENV.fetch("CLOUDFLARE_API_TOKEN")
  c.namespace  = "default" # optional, defaults to "default"
  c.timeout    = 30        # optional
end

client = Cloudflare::Artifacts::Client.new

Or pass options per client

client = Cloudflare::Artifacts::Client.new(
  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
  api_token:  ENV.fetch("CLOUDFLARE_API_TOKEN"),
  namespace:  "ci"
)

Or supply an explicit Configuration

config = Cloudflare::Artifacts::Configuration.new(
  account_id: "...",
  api_token:  "...",
  namespace:  "ci"
)
client = Cloudflare::Artifacts::Client.new(config)

Or load from environment / file

# From ENV — reads:
#   CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN,
#   CLOUDFLARE_ARTIFACTS_NAMESPACE, CLOUDFLARE_API_BASE_URL,
#   CLOUDFLARE_ARTIFACTS_TIMEOUT, CLOUDFLARE_ARTIFACTS_USER_AGENT
Cloudflare::Artifacts.configuration = Cloudflare::Artifacts::Configuration.from_env

# From a YAML or JSON file
Cloudflare::Artifacts.configuration =
  Cloudflare::Artifacts::Configuration.from_file("config/cloudflare.yml")

Keyword overrides also work when a Configuration is passed — they're merged, leaving the original untouched:

Cloudflare::Artifacts::Client.new(config, namespace: "staging")

Every call returns a Cloudflare::Artifacts::Response (a Data object) exposing result, errors, messages, and result_info from the standard Cloudflare v4 envelope.

Repos

# Create a repo
resp = client.repos.create(
  name: "starter-repo",
  description: "Repository for automation experiments",
  default_branch: "main"
)
remote = resp.result["remote"]
token  = resp.result["token"]

# List repos (supports limit, cursor, search, sort, direction)
client.repos.list(limit: 50, sort: "updated_at", direction: "desc")

# Get a repo
client.repos.get("starter-repo")

# Delete a repo
client.repos.delete("starter-repo")

# Fork a repo
client.repos.fork("starter-repo",
                  name: "starter-repo-copy",
                  default_branch_only: true)

# Import a public HTTPS remote
client.repos.import("react-mirror",
                    url: "https://github.com/facebook/react",
                    branch: "main",
                    depth: 100)

# List tokens for a repo
client.repos.tokens("starter-repo", state: "active")

Tokens

# Mint a short-lived token (TTL in seconds, 60..31_536_000)
resp = client.tokens.create(repo: "starter-repo", scope: "read", ttl: 3600)
plaintext = resp.result["plaintext"]

# Revoke a token
client.tokens.revoke("tok_123")

Per-call namespace override

Override the default namespace per call by passing namespace::

client.repos.get("starter-repo", namespace: "ci")

Error handling

Non-2xx responses raise typed errors. All inherit from Cloudflare::Artifacts::APIError:

begin
  client.repos.get("missing")
rescue Cloudflare::Artifacts::NotFoundError => e
  e.status # => 404
  e.errors # => [{ "code" => 1000, "message" => "Repo not found" }]
end

Available subclasses: BadRequestError, AuthenticationError, ForbiddenError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, ServerError.

Customizing Faraday

Configuration exposes adapter, timeout, base_url, and user_agent:

Cloudflare::Artifacts.configure do |c|
  c.adapter = :net_http_persistent
  c.timeout = 60
  c.user_agent = "myapp/1.0"
end

For tests, use the Faraday test adapter — the adapter value can be [symbol, *args]:

stubs = Faraday::Adapter::Test::Stubs.new
client = Cloudflare::Artifacts::Client.new(
  account_id: "acct", api_token: "tok",
  adapter: [:test, stubs]
)

Development

bundle exec rake # run tests + rubocop

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/songjiz/cloudflare-artifacts.

License

The gem is available as open source under the terms of the MIT License.