🌐 Ecosystem Integration Guide

Connect gem-ci with the broader Ruby ecosystem and external development tools

🎯 Overview

gem-ci is designed to integrate seamlessly with the Ruby ecosystem and popular development tools. This guide covers all available integrations and how to set them up.

💎 Ruby Ecosystem Integration

RubyGems.org

Automated Publishing:

1
2
3
4
5

# .github/workflows/06-release.yml automatically handles:
- gem build
- gem push (with RUBYGEMS_API_KEY)
- Version management
- Release notes generation

Setup Requirements:

  1. Create RubyGems account
  2. Generate API key with push permissions
  3. Add RUBYGEMS_API_KEY to repository secrets
  4. Configure gemspec metadata

Enhanced Gemspec:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# your-gem.gemspec
Gem::Specification.new do |spec|
  spec.name = "your-gem"
  spec.version = YourGem::VERSION
  
  # Ecosystem metadata
  spec.metadata = {
    "homepage_uri" => "https://github.com/you/your-gem",
    "source_code_uri" => "https://github.com/you/your-gem",
    "documentation_uri" => "https://you.github.io/your-gem",
    "changelog_uri" => "https://github.com/you/your-gem/blob/main/CHANGELOG.md",
    "bug_tracker_uri" => "https://github.com/you/your-gem/issues",
    "rubygems_mfa_required" => "true"
  }
  
  # Security features
  spec.cert_chain = ["certs/your-cert.pem"]
  spec.signing_key = File.expand_path("~/.ssh/gem-private_key.pem")
end

Bundler Integration

Automatic Gemfile.lock Updates:

1
2
3
4
5
6
7
8
9
10
11

# Dependabot automatically updates Gemfile.lock
# .github/dependabot.yml handles:
version: 2
updates:
  - package-ecosystem: "bundler"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      development:
        patterns: ["rspec*", "rubocop*", "yard*"]

Bundle Audit Integration:

1
2
3
4
5

# .github/workflows/03-security.yml includes:
- name: Bundle Audit
  run: |
    bundle exec bundle-audit check --update
    bundle exec bundle-audit check --ignore CVE-YYYY-XXXX

Ruby Version Management

Multiple Ruby Support (optional):

1
2
3
4
5
6
7
8
9

# Extend CI for multiple Ruby versions
strategy:
  matrix:
    ruby-version: ['3.1', '3.2', '3.3']
    os: [ubuntu-latest, macos-latest]
  exclude:
    # Cost optimization - skip expensive combinations
    - ruby-version: '3.1'
      os: macos-latest

Ruby Version Compatibility:

1
2
3
4
5
6
7
8

# .ruby-version
3.3.0

# Gemfile
ruby "~> 3.3.0"

# gemspec
spec.required_ruby_version = ">= 3.1.0"

🔧 Development Tools Integration

IDE Integration

VS Code Integration:

1
2
3
4
5
6
7
8
9
10
11
12

// .vscode/settings.json
{
  "ruby.lint": {
    "rubocop": {
      "useBundler": true
    }
  },
  "ruby.format": "rubocop",
  "files.associations": {
    "*.yml.erb": "yaml"
  }
}

RubyMine Integration:

1
2
3
4
5
6

# .idea/runConfigurations/
# Automatic detection of:
- RSpec test runner
- RuboCop linting
- YARD documentation
- Git workflows

Editor Configuration

EditorConfig:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.rb]
indent_style = space
indent_size = 2

[*.yml]
indent_style = space  
indent_size = 2

📊 Analytics & Monitoring Integration

GitHub Insights

Built-in Analytics:

Custom Analytics:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// scripts/analytics.js
const octokit = new Octokit({
  auth: process.env.GITHUB_TOKEN
});

// Fetch repository metrics
const metrics = await octokit.rest.repos.getCommunityProfileMetrics({
  owner: 'your-username',
  repo: 'your-repo'
});

// Track gem downloads
const gemStats = await fetch('https://rubygems.org/api/v1/gems/your-gem.json')
  .then(res => res.json());

console.log(`Downloads: ${gemStats.downloads}`);

External Monitoring Services

Datadog Integration:

1
2
3
4
5
6
7
8
9
10
11
12

# In workflows, send custom metrics
- name: Send metrics to Datadog
  run: |
    curl -X POST "https://api.datadoghq.com/api/v1/series" \
      -H "DD-API-KEY: $" \
      -d '{
        "series": [{
          "metric": "gem.ci.duration",
          "points": [['$(date +%s)', $]],
          "tags": ["gem:your-gem", "workflow:ci"]
        }]
      }'

New Relic Integration:

1
2
3
4
5
6
7
8
9
10
11
12

# In your gem
require 'newrelic_rpm'

class YourGem::Performance
  include NewRelic::Agent::Instrumentation::ControllerInstrumentation
  
  def critical_method
    # Automatically tracked
  end
  
  add_transaction_tracer :critical_method
end

🔐 Security Service Integration

Snyk Integration

Vulnerability Scanning:

1
2
3
4
5
6
7

# .github/workflows/security-extended.yml
- name: Snyk Security Scan
  uses: snyk/actions/ruby@master
  env:
    SNYK_TOKEN: $
  with:
    args: --severity-threshold=high

CodeClimate Integration

Code Quality Monitoring:

1
2
3
4
5
6
7
8

# .github/workflows/04-quality.yml
- name: CodeClimate Coverage
  uses: paambaati/codeclimate-action@v5.0.0
  env:
    CC_TEST_REPORTER_ID: $
  with:
    coverageCommand: bundle exec rspec
    coverageLocations: coverage/lcov.info:lcov

📚 Documentation Integration

YARD Documentation

Enhanced Documentation:

1
2
3
4
5
6
7
8

# .yardopts
--markup markdown
--markup-provider kramdown
--output-dir docs/api
--protected
--private
--title "Your Gem API Documentation"
lib/**/*.rb

Documentation Hosting:

1
2
3
4
5
6
7
8

# .github/workflows/04-quality.yml includes:
- name: Generate YARD docs
  run: bundle exec yard doc
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: $
    publish_dir: ./docs

RubyDoc.info Integration

Automatic Documentation:

🤝 Community Integration

GitHub Community Features

Issue Templates:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: File a bug report
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  
  - type: input
    id: version
    attributes:
      label: Gem Version
      description: What version of the gem are you running?
      placeholder: ex. 1.2.3
    validations:
      required: true

Pull Request Templates:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<!-- .github/pull_request_template.md -->
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature  
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] Added new tests for changes
- [ ] Updated documentation

## Checklist
- [ ] Follows code style guidelines
- [ ] Self-review completed
- [ ] Added descriptive commit messages

Community Health Files

Code of Conduct:

1
2
3
4
5
6

# CODE_OF_CONDUCT.md
# Contributor Covenant Code of Conduct

## Our Pledge
We pledge to make participation in our community a harassment-free
experience for everyone...

Contributing Guide:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# CONTRIBUTING.md
# Contributing to Your Gem

## Development Setup
1. Fork the repository
2. Clone your fork
3. Run `bundle install`
4. Run tests with `bundle exec rspec`

## Submitting Changes
1. Create a feature branch
2. Make your changes
3. Add tests for your changes
4. Run the test suite
5. Submit a pull request

🔄 CI/CD Integration

External CI Services

Travis CI Integration (legacy support):

1
2
3
4
5
6
7
8

# .travis.yml
language: ruby
rvm:
  - 3.3.0
cache: bundler
script:
  - bundle exec rspec
  - bundle exec rubocop

CircleCI Integration:

1
2
3
4
5
6
7
8
9
10

# .circleci/config.yml  
version: 2.1
jobs:
  test:
    docker:
      - image: cimg/ruby:3.3
    steps:
      - checkout
      - run: bundle install
      - run: bundle exec rspec

Deployment Integration

Heroku Integration:

1
2
3
4
5
6
7

# For gems that include web components
- name: Deploy to Heroku
  uses: akhileshns/heroku-deploy@v3.12.12
  with:
    heroku_api_key: $
    heroku_app_name: "your-gem-demo"
    heroku_email: "your@email.com"

Docker Integration:

1
2
3
4
5
6
7
8
9

# Dockerfile for gem development/testing
FROM ruby:3.3-alpine

WORKDIR /app
COPY Gemfile* ./
RUN bundle install

COPY . .
CMD ["bundle", "exec", "rspec"]

🎛️ Configuration Management

Environment-specific Configs

Development Configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# config/development.yml
database_url: "sqlite3:development.db"
log_level: "debug"
cache_enabled: false

# config/test.yml  
database_url: "sqlite3::memory:"
log_level: "warn"
cache_enabled: false

# config/production.yml
database_url: <%= ENV['DATABASE_URL'] %>
log_level: "info"
cache_enabled: true

Feature Flags

Environment-based Features:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# lib/your_gem/config.rb
module YourGem
  class Config
    def self.feature_enabled?(feature)
      case feature
      when :advanced_caching
        ENV['ENABLE_ADVANCED_CACHING'] == 'true'
      when :experimental_features
        ENV['RAILS_ENV'] == 'development'
      else
        false
      end
    end
  end
end

📦 Package Manager Integration

Alternative Package Managers

GitHub Packages:

1
2
3
4
5
6
7

# .github/workflows/06-release.yml
- name: Publish to GitHub Packages
  run: |
    gem build *.gemspec
    gem push --key github --host https://rubygems.pkg.github.com/USERNAME *.gem
  env:
    GEM_HOST_API_KEY: $

Private Gem Servers:

1
2
3
4
5

# Gemfile
source 'https://rubygems.org'
source 'https://your-private-gem-server.com' do
  gem 'private-gem'
end

🔍 Search & Discovery Integration

Awesome Lists Integration

Get your gem included in awesome lists:

Submission Requirements:

Search Optimization

GitHub Topics:

1
2
3
4
5
6

# In repository settings, add topics:
- ruby
- gem
- automation
- ci-cd  
- github-actions

RubyGems.org Optimization:

1
2
3
4

# Enhanced gemspec for discoverability
spec.summary = "Concise, searchable summary"
spec.description = "Detailed description with keywords for search"
spec.metadata["keywords"] = "automation,ci,github-actions,ruby"

🚀 Performance Integration

Benchmarking Integration

Benchmark Tools:

1
2
3
4
5
6
7
8
9

# benchmark/performance.rb
require 'benchmark/ips'
require 'your_gem'

Benchmark.ips do |x|
  x.report('method_a') { YourGem.method_a }
  x.report('method_b') { YourGem.method_b }
  x.compare!
end

Performance Monitoring:

1
2
3
4
5

# .github/workflows/performance.yml
- name: Run benchmarks
  run: |
    bundle exec ruby benchmark/performance.rb > benchmark-results.txt
    # Compare with baseline and alert on regression

💡 Best Practices

Integration Strategy

  1. Start Simple: Begin with core integrations (RubyGems, GitHub)
  2. Add Gradually: Introduce new integrations based on needs
  3. Monitor Impact: Track how integrations affect performance
  4. Document Everything: Keep integration documentation current

Maintenance Approach

  1. Regular Updates: Keep integration dependencies current
  2. Test Integrations: Verify integrations work after updates
  3. Monitor Costs: Track costs of external service integrations
  4. Have Fallbacks: Ensure core functionality works without integrations

Security Considerations

  1. Limit Permissions: Use minimal permissions for external services
  2. Rotate Keys: Regularly rotate API keys and tokens
  3. Monitor Access: Track access patterns for unusual activity
  4. Audit Integrations: Regularly review active integrations

Ready to integrate? Start with the core Ruby ecosystem integrations and expand based on your project’s specific needs!