Submitting your plugin to RubyGems.org and the logstash-plugins repository

Logstash uses RubyGems.org as its repository for all pluginartifacts. Once you have developed your new plugin, you can make it available toLogstash users by simply publishing it to RubyGems.org.

Licensing

Logstash and all its plugins are licensed underApache License, version 2 ("ALv2").If you make your plugin publicly available via RubyGems.org,please make sure to have this line in your gemspec:

  • s.licenses = ['Apache License (2.0)']

Publishing to RubyGems.org

To begin, you’ll need an account on RubyGems.org

After creating an account,obtain an APIkey from RubyGems.org. By default, RubyGems uses the file ~/.gem/credentialsto store your API key. These credentials will be used to publish the gem.Replace username and password with the credentials you created atRubyGems.org:

curl -u username:password https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentialschmod 0600 ~/.gem/credentials

Before proceeding, make sure you have the right version in your gemspec fileand commit your changes.

  • s.version = '0.1.0'

To publish version 0.1.0 of your new logstash gem:

bundle installbundle exec rake vendorbundle exec rspecbundle exec rake publish_gem
Note

Executing rake publish_gem:

  1. Reads the version from the gemspec file (s.version = '0.1.0')
  2. Checks in your local repository if a tag exists for that version. If the tagalready exists, it aborts the process. Otherwise, it creates a new version tagin your local repository.
  3. Builds the gem
  4. Publishes the gem to RubyGems.org

That’s it! Your plugin is published! Logstash users can now install your pluginby running:

bin/plugin install logstash-output-mypluginname

Contributing your source code to logstash-plugins

It is not required to contribute your source code tologstash-plugins github organization, butwe always welcome new plugins!

Benefits

Some of the many benefits of having your plugin in the logstash-pluginsrepository are:

  • Discovery Your plugin will appear in the Logstash Reference,where Logstash users look first for plugins and documentation.
  • Documentation Your plugin documentation will automatically be added to theLogstash Reference.
  • Testing With our testing infrastructure, your plugin will be continuouslytested against current and future releases of Logstash. As a result, users willhave the assurance that if incompatibilities arise, they will be quicklydiscovered and corrected.

Acceptance Guidelines

  • Code Review Your plugin must be reviewed by members of the community forcoherence, quality, readability, stability and security.
  • Tests Your plugin must contain tests to be accepted. These tests are alsosubject to code review for scope and completeness. It’s ok if you don’t knowhow to write tests — we will guide you. We are working on publishing a guide tocreating tests for Logstash which will make it easier. In the meantime, you canrefer to http://betterspecs.org/ for examples.

To begin migrating your plugin to logstash-plugins, simply create a newissue inthe Logstash repository. When the acceptance guidelines are completed, we willfacilitate the move to the logstash-plugins organization using the recommendedgithub process.