4mgemstash-private-gems24m(7) 4mgemstash-private-gems24m(7)

<!– Automatically generated by Pandoc –>

1mPrivate Gems0m

    Stashing  private  gems in your Gemstash server requires a bit of addi-
    tional setup.  If you haven't read through the  Quickstart  Guide,  you
    should  do  that  first.  By the end of this guide, you will be able to
    interact with your Gemstash server to store and retrieve  your  private
    gems.

1mAuthorizing0m
    1mIMPORTANT  NOTE: 22mDo not use the actual key value in this document, oth-
    erwise your Gemstash server will be vulnerable to anyone who  wants  to
    try to use the key against your server.  Instead of the key value here,
    use whatever key is generated from running the commands.

    In  order to push a gem to your Gemstash server, you need to first cre-
    ate an API key.  Utilize the gemstash authorize command to  create  the
    API key:

           $ gemstash authorize
           Your new key is: e374e237fdf5fa5718d2a21bd63dc911

    This  new key can push, yank, and fetch gems from your Gemstash server.
    Run gemstash authorize with just the permissions you want to limit what
    the key will be allowed to do.  You can similarly update a specific key
    by providing it via the --key option:

           $ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911

    When no permissions are provided (like the first example), the key will
    be authorized for all  permissions.   Leave  the  key  authorized  with
    everything if you want to use it to try all private gem interactions:

           $ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911

    With  the  key  generated,  you'll need to tell Rubygems about your new
    key.  If you've pushed a gem to https://rubygems.org, then you will al-
    ready have a credentials file to add the key to.  If not, run the  fol-
    lowing commands before modifying the credentials file:

           $ mkdir -p ~/.gem
           $ touch ~/.gem/credentials
           $ chmod 0600 ~/.gem/credentials

    Add  your new key to credentials such that it looks something like this
    (but make sure not to remove any existing keys):

           # ~/.gem/credentials
           ---
           :test_key: e374e237fdf5fa5718d2a21bd63dc911

    The name test_key can be anything you want, but you will need to remem-
    ber it and use it again later in this guide for the --key option.

1mCreating a Test Gem0m
    You'll need a test gem before you can play with private  gems  on  your
    Gemstash server.  If you have a gem you can use, move along to the next
    section.  You can start by instantiating a test gem via Bundler:

           $ bundle gem private-example

    You'll  need  to add a summary and description to the new gem's gemspec
    file in order to successfully build it.  Once you've built the gem, you
    will be ready to push the new gem.

           $ cd private-example
           $ rake build

    You  will  now  have   a   gem   at   private-example/pkg/private-exam-
    ple-0.1.0.gem.

1mPushing0m
    If your Gemstash server isn't running, go ahead and start it:

           $ gemstash start

    Push your test gem using Rubygems:

           $ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem

    The /private portion of the --host option tells Gemstash you are inter-
    acting  with the private gems.  Gemstash will not let you push, or yank
    from anything except /private.

1mBundling0m
    Once your gem is pushed to your Gemstash server, you are ready to  bun-
    dle  it.  Create a Gemfile and specify the gem.  You will probably want
    to wrap the private gem in a source block, and let the rest of Gemstash
    handle all other gems:

           # ./Gemfile
           source "http://localhost:9292"
           gem "rubywarrior"

           source "http://localhost:9292/private" do
             gem "private-example"
           end

    Notice that the Gemstash server  points  to  /private  again  when  in-
    stalling  your  private  gem.   Go ahead and bundle to install your new
    private gem:

           $ bundle

1mYanking0m
    If you push a private gem by  accident,  you  can  yank  the  gem  with
    Rubygems:

           $ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0

    Like  with  pushing, the /private portion of the host option tells Gem-
    stash you are interacting with private gems.  Gemstash  will  only  let
    you  yank  from  /private.   Unlike  pushing,  Rubygems doesn't support
    --host for yank (yet),  so  you  need  to  specify  the  host  via  the
    RUBYGEMS_HOST environment variable.

1mProtected Fetching0m
    By  default, private gems and specs can be accessed without authentica-
    tion.

    Private gems often require protected fetching.  For backwards  compati-
    bility  this  is disabled by default, but can be enabled via $ gemstash
    setup command.

    When protected fetching is enabled API keys with the permissions all or
    fetch can be used to download gems and specs.

    On the Bundler side, there are a few ways to configure credentials  for
    a given gem source:

    Add credentials globally:

           $ bundle config my-gemstash.dev api_key

    Add credentials in Gemfile:

           source "https://api_key@my-gemstash.dev"

    However,  it's not a good practice to commit credentials to source con-
    trol.  A recommended solution is to use  Bundler's  configuration  keys
    (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.:

           $ export BUNDLE_MYGEMSTASH__DEV=api_key

    Behind  the  scene,  Bundler  will pick up the ENV var according to the
    host name (e.g. mygemstash.dev) and add to URI.userinfo for making  re-
    quests.

    The API key is treated as a HTTP Basic Auth username and any HTTP Basic
    password supplied will be ignored.

                             October 8, 2015       4mgemstash-private-gems24m(7)