Octokit.rb Documentation

Since Octokit uses Faraday, you can inject a logger into the middleware stack to inspect underlying HTTP requests and responses. This is useful for debugging authentication or payload issues.

stack = Faraday::RackBuilder.new do |builder|
  builder.use Faraday::Retry::Middleware, exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Octokit::ServerError]
  builder.use Octokit::Middleware::FollowRedirects
  builder.use Octokit::Response::RaiseError
  builder.use Octokit::Response::FeedParser
  builder.response :logger do |logger|
    logger.filter(/(Authorization: "(token|Bearer) )(\w+)/, '\1[REMOVED]')
  end
  builder.adapter Faraday.default_adapter
end
Octokit.middleware = stack

client = Octokit::Client.new
client.user 'pengwynn'

To set up a local development environment for hacking on Octokit.rb, use the provided bootstrap script to install dependencies and prepare the project.

To bootstrap the project:

script/bootstrap

To open a Ruby console to interact with Octokit locally:

script/console

Using the scripts in ./script ensures that your dependencies are up-to-date compared to running bundle exec commands directly.

To improve performance and respect rate limits, you can add faraday-http-cache to your middleware stack. This will cache responses based on ETag fingerprints and serve them back for subsequent 304 responses.

# Add gem 'faraday-http-cache' to your Gemfile

stack = Faraday::RackBuilder.new do |builder|
  builder.use Faraday::HttpCache, serializer: Marshal, shared_cache: false
  builder.use Octokit::Response::RaiseError
  builder.adapter Faraday.default_adapter
end
Octokit.middleware = stack

You can install Octokit by running the gem install command or by adding it to your Gemfile.

To install via Rubygems:

gem install octokit

To add to your Gemfile:

gem "octokit"

Then, access the library in your Ruby code using:

require 'octokit'

By default, Octokit does not timeout network requests. To prevent blocking your server, pass Faraday timeout settings into connection_options via the configuration block.

Octokit.configure do |c|
  c.api_endpoint = ENV.fetch('GITHUB_API_ENDPOINT', 'https://api.github.com/')
  c.connection_options = {
    request: {
      open_timeout: 5,
      timeout: 5
    }
  }
end

Many Octokit attributes automatically look for default values in environment variables before falling back to internal defaults. For example, setting OCTOKIT_API_ENDPOINT will configure the api_endpoint.

To disable deprecation warnings and development preview warnings from being printed to STDOUT, set the environment variable: OCTOKIT_SILENT=true

Octokit allows setting configuration options at the module level using Octokit.configure. These defaults apply to all new client instances created after the configuration is set.

Supported attributes include:

• api_endpoint
• web_endpoint
• access_token
• manage_ghes_endpoint
• manage_ghes_username
• manage_ghes_password

# Set attributes one at a time
Octokit.api_endpoint = 'http://api.github.dev'

# Set attributes in a batch
Octokit.configure do |c|
  c.api_endpoint = 'http://api.github.dev'
  c.web_endpoint = 'http://github.dev'
end

When auto_paginate is enabled, Octokit will automatically fetch and concatenate results from all pages into a single array. Note that this sets the page size to 100 and may consume more of your rate limit.

To enable it for a specific client instance:

client.auto_paginate = true

To enable it globally for all Octokit client instances:

Octokit.configure do |c|
  c.auto_paginate = true
end

client.auto_paginate = true
issues = client.issues 'rails/rails'
issues.length
# => 702

The GitHub API defaults to 30 results per page. You can increase this during client initialization using the per_page option (up to 100).

Octokit::Client.new(access_token: "<token>", per_page: 100)

Octokit::Client.new(access_token: "<your 40 char token>", per_page: 100)

Octokit raises Ruby exceptions when the API returns an error. All exceptions inherit from Octokit::Error and provide access to #response_status, #response_headers, and #response_body.

Common error mappings:

• 400 Bad Request $\rightarrow$ Octokit::BadRequest
• 403 Forbidden (rate limited) $\rightarrow$ Octokit::TooManyRequests

For validation errors, the #errors method returns an Array of Hashes containing detailed information from the API.

If you need to temporarily disable SSL verification during the initial setup of a GitHub Enterprise installation, you can modify the connection_options on your client instance.

Warning: Ensure you set :verify back to true once setup is complete to maintain secure communication.

client.connection_options[:ssl] = { :verify => false }