Ruby

Add ruby under targets to generate a Ruby SDK gem.

{
  "targets": {
    "ruby": {
      "gemName": "acme_api",
      "destinations": {
        "production": {
          "repo": "acme/acme-ruby"
        }
      },
      "publish": {
        "rubygems": {
          "authMethod": "oidc",
          "releaseEnvironment": "production"
        }
      }
    }
  }
}

Setting up publishing: Ruby publishing guide. How releases are cut: Publishing.

gemName

Type: string

Ruby gem name.

Defaults to a snake_case name derived from organization.name, which is what RubyGems prefers for a gem that occupies a single namespace: a dash is read there as a namespace separator, so acme-widget conventionally means the Acme::Widget gem whose entrypoint is lib/acme/widget.rb, and the generated gem is flat.

A dash spelled here is preserved, so a gem already published under a kebab-case name (acme-billing) keeps it. Each dash-delimited segment is normalized on its own, so other separators and casing still fold into snake_case — acme.dev becomes acme_dev and MyGem becomes my_gem. Changing this value renames the published gem and the release-please component, so pin it to the current name for a gem that has already shipped.

destinations

Type: object

Per-target GitHub destinations for pushing generated output.

production

Type: object

Primary repository this target's generated output is published to. Setting it turns on the generated GitHub Actions: the CI workflow, the release-please configuration, and the versioning policy. A release workflow is added too when publish enables a registry that needs one; a registry served from git tags publishes from the release tag alone. Without a production destination the target is still generated, but with no workflows.

publish

Type: object

RubyGems publishing configuration.

rubygems

Type: boolean | object

Publishes the Ruby gem to RubyGems. true publishes with the defaults; an object tunes them.

Authenticates with RubyGems trusted publishing (OIDC) by default, registered as a pending publisher at rubygems.org/profile/oidc/pending_trusted_publishers for a gem with no releases yet. With authMethod set to access-token it reads a rubygems.org API key from the RUBYGEMS_API_KEY repository secret instead; a GEM_HOST_API_KEY secret is read when that is unset.

authMethod

Type: "oidc" | "access-token"

How the generated release workflow authenticates with the registry.

oidc uses the registry's OIDC trusted publishing: the publish job exchanges its GitHub Actions id-token for a short-lived, package-scoped token, so no long-lived credential is stored in the destination repository. It is the default wherever the registry supports it, and requires a trusted publisher registered on the registry naming the destination repository, the workflow file the publish job runs from — release-please.yml, the workflow the automated release publishes from (register sdk-release.yml as a second publisher only if the manual re-publish workflow is used) — and the releaseEnvironment when one is set.

access-token publishes with a long-lived token read from a repository secret instead; use it while no trusted publisher is registered yet, then drop the override once one is, unless the registry's own entry says to keep it. Repository secrets live under Settings → Secrets and variables → Actions in the destination repository; an environment secret of the same name overrides one there when releaseEnvironment is set.

This registry's own publish.<registry> entry names the page to register a trusted publisher on, the secret access-token reads, any exception to these defaults, and whether authMethod applies at all.

releaseEnvironment

Type: string

Release environment name used by generated publishing workflows. It renders as the publish job's environment:, so the destination repository's environment protection rules — required reviewers, wait timers, environment secrets — gate the release. Under OIDC trusted publishing the name must also match the environment registered on the trusted publisher, which is how a registry constrains who in a repository may publish; leave the registry's environment field blank when this is unset, since a publisher that names an environment rejects a run without one. When it is set, the publish job can read that environment's secrets as well as the repository's, and an environment secret takes precedence over a repository secret of the same name.

prereleaseType

Type: string

Prerelease channel this target's releases publish on, as a bare semver prerelease identifier (next, beta, rc). It becomes the released version's prerelease suffix — a channel of next releases 1.2.0-next.1 — so the value is held to the shape a semver identifier may take: a letter, then letters, digits and hyphens.

Omit it to release on the stable line. A release train promoting to a conventionally named prerelease branch (alpha, beta, canary, next, preview, rc) adopts that branch's name as its channel, so this only has to be set to name a channel the branch does not, or to put a target on a prerelease line while promoting to a branch named something else.

Constraints: pattern: ^[A-Za-z][0-9A-Za-z-]*$

skip

Type: boolean

When true, the target is not generated.

readmeTitle

Type: string

Heading of this target's generated README, overriding the SDK-wide readme.title. Plain text: markdown in it is shown as written, not rendered.

promotion

Type: "automatic" | "manual"

When a successful build's generated output reaches this target's production destination. automatic, the default, pushes every build, which opens a release pull request. manual holds each build at the staging playground until you promote it.

This changes when the push happens, never what is generated: a manual target still gets the GitHub Actions, release-please configuration, and versioning policy that destinations.production turns on. A target with no production destination is never pushed, whatever this is set to.

Default: "automatic"