Octolead

Octolead is a Ruby client and CLI for GitHub Projects v2, the area where Octokit.rb does not (yet) have a high-level interface because Projects v2 is GraphQL-only.

This gem wraps the Projects v2 GraphQL API with idiomatic Ruby objects and provides an interactive CLI for everyday workflows — starting with creating draft items with assignees, status, dates, and any custom fields.

Installation

gem install octolead

Or in a Gemfile:

gem "octolead"

Authentication

Octolead reads a GitHub token from, in order:

1. access_token: argument passed to Octolead::Client.new
2. GITHUB_TOKEN environment variable
3. gh auth token (the GitHub CLI)

The token needs the project scope. If you use gh:

gh auth refresh -s project

CLI

Create a draft item interactively

octolead item create --owner my-org --number 1

Octolead fetches the project's fields, then prompts for title, body, assignees, each single-select field, each date field, and a view number for the result URL. After confirmation it creates the item and prints the URL.

Create a draft item non-interactively

octolead item create -y \
  --owner my-org \
  --number 1 \
  --title "API のリトライ処理を追加" \
  --assignees ak-inori \
  --field "Status=Todo" \
  --field "Product=aune" \
  --field "Start date=2026-05-16" \
  --field "Target date=2026-05-23" \
  --view 11

--field NAME=VALUE works for any custom field; the value is the option name for single-selects, or YYYY-MM-DD for dates.

Environment defaults

If you always work against the same project, set:

export OCTOLEAD_OWNER=my-org
export OCTOLEAD_PROJECT=1

Then --owner and --number become optional.

Library

require "octolead"

client = Octolead::Client.new # reads token from GITHUB_TOKEN / gh
project = client.project("my-org", 1)

item = project.add_draft(
  title: "バグ修正",
  body: "詳細",
  assignees: ["ak-inori"],
  fields: {
    "Status"      => "Todo",
    "Product"     => "aune",
    "Start date"  => "2026-05-16",
    "Target date" => "2026-05-23",
  }
)

puts item.url(view: 11)
# => https://github.com/orgs/my-org/projects/1/views/11?pane=issue&itemId=...

If you already have an Octokit::Client instance you'd like to share auth with, pass it directly:

octokit = Octokit::Client.new(access_token: ENV["GITHUB_TOKEN"])
client = Octolead::Client.new(octokit: octokit)

Roadmap

Octolead is intentionally released in small increments. Planned scope:

Version	Scope
0.1.0	Draft item creation with field values (current)
0.2.0	Item listing / fetching
0.3.0	Item updates and archival
0.4.0	Adding existing issues/PRs; draft→issue conversion
0.5.0	Field CRUD (create/update/delete fields & options)
0.6.0	Views and workflow management
0.7.0	Project CRUD
1.0.0	Stable API

Contributions toward any of these are welcome.

Development

bin/setup
bundle exec rspec
bundle exec rubocop

Contributing

Bug reports and pull requests are welcome at https://github.com/ak-inori/octolead.

License

MIT.