octopi

Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com).

To install it as a Gem, just run:

  $ sudo gem install octopi

Get notifications via Twitter, following @octopi_gem: http://twitter.com/octopi_gem

Authenticated Usage

Seamless authentication using .gitconfig defaults

If you have your ~/.gitconfig file in place, and you have a [github] section (if you don’t, take a look at this GitHub Guides entry: http://github.com/guides/tell-git-your-user-name-and-email-address), you can use seamless authentication using this method:

  authenticated do |g|
    repo = g.repository("api-labrat")
    (...)
  end

Explicit authentication

Sometimes, you may not want to get authentication data from ~/.gitconfig. You want to use GitHub API authenticated as a third party. For this use case, you have a couple of options too.

1. Providing login and token inline:

  authenticated_with "mylogin", "mytoken" do |g|
    repo = g.repository("api-labrat")
    issue = repo.open_issue :title => "Sample issue",
      :body => "This issue was opened using GitHub API and Octopi"
    puts issue.number
  end

2. Providing a YAML file with authentication information:

Use the following format:

  #
  # Octopi GitHub API configuration file
  #

  # GitHub user login and token
  : github-username
  token: github-token

  # Trace level
  # Possible values:
  #   false - no tracing, same as if the param is ommited
  #   true  - will output each POST or GET operation to the stdout
  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
  trace: curl

And change the way you connect to:

  authenticated_with :config => "github.yml" do |g|
    (...)
  end

Anonymous Usage

This reflects the usage of the API to retrieve information on a read-only fashion, where the user doesn’t have to be authenticated.

Users API

Getting user information

  user = User.find("fcoury")
  puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"

The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.

  user.followers!.each do |u|
    puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
  end

Searching for user

  users = User.find_all("silva")
  puts "#{users.size} users found for 'silva':"
  users.each do |u|
    puts "  - #{u.name}"
  end

Repositories API

  repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
  puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
  puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"

Search:

  repos = Repository.find_all("ruby", "git")
  puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
  repos.each do |r|
    puts "  - #{r.name}"
  end

Issues API integrated into the Repository object:

  issue = repo.issues.first
  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"

Single issue information:

  issue = repo.issue(11)

Commits API information from a Repository object:

  first_commit = repo.commits.first
  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"

Single commit information:

  puts "Diff:"
  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }

Tracing

Levels

You can can use tracing to enable better debugging output when something goes wrong. There are 3 tracing levels:

If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:

  => Trace on: curl
  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
  ===== curl version
  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
  ==================

Enabling

Tracing can be enabled in different ways, depending on the API feature you’re using:

Anonymous (this will be improved later):

  ANONYMOUS_API.trace_level = "trace-level"

Seamless authenticated

  authenticated :trace => "trace-level" do |g|; ...; end

Explicitly authenticated

Current version of explicit authentication requires a :config param to a YAML file to allow tracing. For enabling tracing on a YAML file refer to the config.yml example presented on the Explicit authentication section.

Author

Contributors

In alphabetical order:

Thanks guys!

Copyright

Copyright © 2009 Felipe Coury. See LICENSE for details.

Generated on Friday, July 31 2009 at 05:01:54 PM by YARD 0.2.3.2 (ruby-1.8.6).