# RubyGems {#rubygems}

Takumi Guard setup varies depending on your environment and the features you need. This page covers setup for both local development and GitHub Actions.

## Setup {#setup}

Takumi Guard offers three ways to get started:

- **[Anonymous](#setup-anonymous)** — No token required. Set the mirror URL to enable package blocking.
- **[Email-Verified](#setup-email-verified)** — Use an email-verified token (`tg_anon_…`) for download tracking and breach notifications.
- **[Org User Token](#setup-org-user-token)** — Use an org user token (`tg_org_…`) to track installations across your organization.

Both email-verified and org user tokens use the same [package manager configuration](#setup-bundler).

:::info Paid Feature
Org user tokens require an active Takumi subscription with Guard enabled. See [Pricing & Billing](/docs/t/guard/billing/index.md) for details.
:::

### Anonymous Usage {#setup-anonymous}

You can use Takumi Guard's package blocking without authentication. Simply set the mirror URL to enable malicious package blocking. Download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) are not available, but this is the easiest way to get started.

Configure Bundler with the mirror URL:

```bash
bundle config set --global mirror.https://rubygems.org https://rubygems.flatt.tech/
```

That's it. All `bundle install` commands now route through Takumi Guard.

:::tip Package Manager Compatibility
Takumi Guard supports **Bundler**. Bundler reads the mirror config from `~/.bundle/config`, so no `Gemfile` change is needed.
:::

### Email-Verified Access {#setup-email-verified}

Registering your email address enables download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) in addition to package blocking. If a security advisory is published for a package you previously downloaded, a notification is sent to your registered email address. No Shisho Cloud account is required, and this is free of charge.

:::info
If you already have an org user token or email-verified token from using Takumi Guard with npm or PyPI, you don't need to register again — the same token works for RubyGems.
:::

**Step 1: Register your email**

```bash
curl -X POST https://rubygems.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "en"}'
```

The `language` field is optional and defaults to `"en"`. Set it to `"ja"` to receive emails in Japanese. This preference is stored with your token and applies to all future emails, including breach notifications.

You'll receive a welcome email within a few seconds.

**Step 2: Get your API key from the email**

Your API key is included directly in the welcome email. The key is ready to use immediately — no link to click.

:::warning
Save this key somewhere secure. If you need a new one, you can regenerate it anytime: `curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://rubygems.flatt.tech/api/v1/tokens/regenerate`
:::

Once you have a token, proceed to "Configure Bundler" below.

### Org User Tokens {#setup-org-user-token}

Org user tokens (`tg_org_…`) can be issued from the Takumi / Shisho Cloud console, or by a bot via the Guard API. See [Token Management](/docs/t/guard/features/token-management.md#user-tokens) for details on issuing tokens.

Once you have a token, proceed to "Configure Bundler" below.

### Configure Bundler {#setup-bundler}

Configure Bundler with your token. This is the recommended and primary setup method:

```bash
bundle config set --global mirror.https://rubygems.org https://token:YOUR_API_KEY@rubygems.flatt.tech/
```

This redirects all `bundle install` calls transparently through Takumi Guard. No changes to your `Gemfile` are needed — Bundler automatically applies the mirror configuration.

Your `bundle install` commands now authenticate with your token, enabling download tracking and breach notifications.

### GitHub Actions {#setup-ci}

To integrate Takumi Guard into your GitHub Actions workflow, use the `flatt-security/setup-takumi-guard-rubygems` GitHub Action. You can use it anonymously or linked to an organization.

#### Anonymous Mode {#setup-ci-anonymous}

If you don't have a Shisho Cloud account yet, you can still use Takumi Guard in CI for package blocking. Omit the `bot-id` input:

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        # No bot-id — anonymous mode, blocking only

      - run: bundle install
      - run: bundle exec rspec
```

In anonymous mode, the action only configures the Bundler mirror for `rubygems.org`. Blocked packages are still rejected with a 403 error, but download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) are not available.

#### With Shisho Cloud Organization {#setup-ci-org}

Linking to a Shisho Cloud organization enables organization-level download tracking and [breach notifications](/docs/t/guard/features/breach-notifications.md) (via webhook). No long-lived secrets need to be stored in your CI environment. Authentication is performed securely by exchanging a GitHub OIDC token for a short-lived access token via the Shisho Cloud STS service.

**Prerequisites:**

1. A bot identity registered in Shisho Cloud. Copy the **Bot ID** from the registry settings page in the Shisho Cloud console.
2. The `id-token: write` and `contents: read` permissions in your workflow job.

**Step 1: Add the action to your workflow**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC token exchange
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        with:
          bot-id: "BT01EXAMPLE..." # Copy from Shisho Cloud console

      - run: bundle install
      - run: bundle exec rspec
```

The action handles the full OIDC exchange automatically:

1. Requests a GitHub OIDC token (with the registry host as audience)
2. Exchanges it for a short-lived Takumi Guard access token via the STS service
3. Configures the Bundler mirror for `rubygems.org` to use the Takumi Guard registry with that token

:::info
The Bot ID is not a secret — it is a public reference key used to look up the allowlist during token exchange. You can commit it directly in your workflow file. The Shisho Cloud console provides a ready-to-copy workflow snippet with the Bot ID pre-filled.
:::

The access token expires after 30 minutes by default (configurable up to 24 hours via the `expires-in` input).

#### Action Inputs Reference {#action-inputs}

| Input          | Required | Default                        | Description                                                             |
| -------------- | -------- | ------------------------------ | ----------------------------------------------------------------------- |
| `bot-id`       | No       | —                              | Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.        |
| `set-mirror`   | No       | `true`                         | Set to `false` if you manage the Bundler mirror yourself.               |
| `registry-url` | No       | `https://rubygems.flatt.tech`  | Custom registry URL. Override only if directed by Shisho Cloud support. |
| `sts-url`      | No       | `https://sts.cloud.shisho.dev` | STS service URL used for the OIDC → access-token exchange.              |
| `expires-in`   | No       | `1800` (seconds)               | Access token lifetime in seconds. Maximum `86400` (24 hours).           |

For the full list of inputs and outputs, see the [action repository](https://github.com/flatt-security/setup-takumi-guard-rubygems).

## Using with Private Gems {#private-gems}

Takumi Guard is a read-only security proxy for public gems. If your project depends on private gems, you need to configure your `Gemfile` so that private gems bypass Takumi Guard and are fetched directly from their registry.

### Gemfile Source Block {#private-gems-source-block}

Bundler supports per-source registry routing via the `source` block in your `Gemfile`. By adding a source block for your private registry, you can route private gems directly while public gems continue to go through Takumi Guard.

For example, if your organization hosts private gems on a custom gem server:

Keep pointing at `rubygems.org` in your `Gemfile` — the `bundle config mirror` setting above redirects requests to Takumi Guard automatically. Only the private registry needs an explicit source block.

```ruby
# Public gems → redirected to Takumi Guard by the bundle config mirror
source 'https://rubygems.org' do
  gem 'rails', '~> 7.1'
  gem 'bundler', '~> 2.4'
end

# Private gems → bypass Takumi Guard, fetch directly
source 'https://gem-server.your-company.com/' do
  gem 'your-company-utils'
  gem 'your-company-auth'
end
```

With this configuration, Bundler routes requests as follows:

- `gem 'rails'` → fetched via Takumi Guard (redirected by the mirror config, security scanning applied)
- `gem 'your-company-utils'` → fetched directly from your private registry (bypasses Takumi Guard)

:::tip
You do not need to put the Takumi Guard URL or API key directly in your `Gemfile`. With `bundle config mirror` configured, your `Gemfile` can keep pointing at `rubygems.org` — this way your token is never committed to version control.
:::

:::warning
Private gems routed to a different registry bypass Takumi Guard's security scanning. This is acceptable for your organization's own packages, but be aware that those packages will not be checked against the blocklist.
:::

## Verify Your Setup {#verify-setup}

To confirm that Takumi Guard is working, try installing the harmless test gem `hola-takumi` at the blocked version `0.1.0`. `hola-takumi` is a harmless test gem published by GMO Flatt Security for verifying Takumi Guard's behavior.

```bash
cd $(mktemp -d) && printf 'source "https://rubygems.org"\ngem "hola-takumi", "0.1.0"\n' > Gemfile && bundle install
```

If Takumi Guard is configured correctly, the proxy filters out this version and Bundler fails with the following error:

```
Fetching gem metadata from https://rubygems.flatt.tech/.
Could not find gem 'hola-takumi (= 0.1.0)' in rubygems repository
https://rubygems.org/ or installed locally.
```

:::note
If `hola-takumi 0.1.0` is already installed in your local gem environment, Bundler uses the local copy instead of fetching from the proxy — the command then succeeds with `Using hola-takumi 0.1.0` instead of failing. Remove it first and re-run:

```bash
gem uninstall hola-takumi --all --force
```

:::

## Publishing {#publishing}

Takumi Guard is a read-only security proxy. Publishing packages is not affected because `gem push` and similar tools communicate directly with `https://rubygems.org`, not through the mirror URL.

```bash
gem push your-gem-1.0.0.gem
```

No changes to your publishing workflow are needed.

## Uninstall {#uninstall}

To stop using Takumi Guard, revert your mirror settings.

### Local Environment {#uninstall-local}

Remove the Takumi Guard mirror configuration from Bundler:

```bash
bundle config unset --global mirror.https://rubygems.org
```

### GitHub Actions {#uninstall-ci}

Remove the Takumi Guard action from your workflow file:

```yaml
# Remove the following step
- uses: flatt-security/setup-takumi-guard-rubygems@v1
```

:::info
Once the action is removed, `bundle install` will access the public RubyGems registry directly. No lockfile changes are required.
:::