Using GitHub CLI from Lua

[williambdean]

Interested in using the GitHub CLI, REST API, or GraphQL API in your Lua code? Octo.nvim provides a module gh to work with them.

Background on gh.run Command

Important

This is just background and is not the recommended way to use the GitHub CLI with the plugin.

The gh.run command is used to run arbitrary GitHub CLI commands. It uses plenary.job under the hood.

local gh = require "octo.gh"

gh.run {
  args = { "pr", "list" },
}

In addition to args, there are parameters to handle:

• mode: async or sync (default is async)
• cb: callback function for async mode
• stream_cb: callback function for streaming output in async mode
• headers: table of headers to pass to the command. There are some good defaults already.
• debug: set the GH_DEBUG environment to print requests to stderr. Read more here.

This function uses timeout, hostname, the GitHub CLI binary specified in octo configuration. It also ensures that the environment variables are set correctly.

Synchronous Calls with mode

By default, all calls are made async. If the output is desired, this is a good route.

local stdout, stderr = gh.run {
  args = { "pr", "list" },
  mode = "sync",
}

Otherwise, pass a callback with cb.

Passing callbacks to cb

Callbacks will take stdout and stderr.

There is a convenience function gh.create_callback which handles success and failure cases.

local cb = gh.create_callback {
  success = function(stdout)
    print("SUCCESS!")
    print(stdout)
  end,
  failure = function(stderr)
    print("FAILURE!")
    print(stderr)
  end,
}

Tip

By default, the success is utils.info and failure is utils.error so gh.create_callback() is easy first start.

Arbitrary GitHub CLI Commands

Instead of using gh.run directly, the gh module provides wrapper which builds these commands. It is meant to be as close to the CLI syntax as possible. For instance, gp pr list is:

gh.pr.list {}

Note

This calls gh.run { args = { "pr", "list" } }

Any of the other opts from gh.run can be passed to opts. For instance, making a synchronous call:

local stdout, stderr = gh.pr.list {
  opts = { mode = "sync"}, 
}

Note

This calls gh.run { args = { "pr", "list" }, mode = "sync" }

Arguments and Flags

Any additional arguments and options are added to args. The parameter opts is saved to pass to gh.run. For example, running the command gh pr list --json id,number,title --search is:merged is:

gh.pr.list {
  json = "id,number,title",
  search = "is:merged",
}

Note

This calls gh.run { args = { "pr", "list", "--json", "id,number,title", "--search", "is:merged"} }

Positional arguments

Just pass positional arguments to the table. For example,

gh issue edit 1

is just

gh.issue.edit { 1 } 

Tip

Underscores in keys will become hyphens. For example, gh issue edit 1 --add-label bug is gh.issue.edit { 1, add_label = "bug" }.

User Input Hangs

Warning

Some commands require user input which will make the program hang. For example gh pr create

Give each command a try to see if it works in the terminal. Provide the necessary input to avoid.

Using extensions

The commands are not being checked so even installed extensions can be used. For instance, gh copilot explain "tmux has-session":

local opts = {
  cb = gh.create_callback()
}

gh.copilot.explain {
  "tmux has-sessions",
  opts = opts,
}

Or gh models run gpt-4o-mini "How many planets are in the solar system":

local gh = require "octo.gh"

local opts = { cb = gh.create_callback() }

local model = "gpt-4o-mini"
local prompt = "How many planets are in the solar system"

gh.models.run {
  model,
  prompt,
  opts = opts,
}

REST API

Access the REST API similar to with the GitHub CLI commands:

gh api <endpoint> [flags]

For example, gh api /repos/:owner/:repo/issues is:

local endpoint = "/repos/:owner/:repo/issues"

local opts = { cb = gh.create_callback() }

gh.api {
  endpoint,
  opts = opts
}

Arguments and options can be passed just like they were above! This includes the fields and raw fields. For example, gh api --method GET search/issues -f q='repo:cli/cli is:open remote' is done by passing table to key f:

local opts = { cb = gh.create_callback() }

local endpoint = "search/issues"

gh.api {
  endpoint,
  method = "GET",
  f = {
    q = "repo:cli/cli is:open remote",
  },
  opts = opts,
}

Wrappers for HTTP Methods

Use gh.api.get specifically for GET requests.

local endpoint = "/octocat

local opts = { cb = gh.create_callback()}

gh.api.get {
  endpoint,
  opts = opts,
}

Same goes for POST, PATCH, PUT, DELETE requests.

Format Endpoint

Use the format parameter in the table to format a provided endpoint. Any name in brackets {} will be replaced. For example,

local endpoint = "repos/{owner}/{repo}/issues"

gh.api.get {
  endpoint,
  format = { owner = "pwntester", repo = "octo.nvim" },
}

Nested Parameters

For nested parameters, use a table.

For example, creating an issue with REST API allows for lists of labels and assignees. This is done by passing a table to the key.

gh.api.post {
  "/repos/:owner/:repo/issues",
  f = {
    title = "Found a difficult bug",
    body = "Please help fix this bug",
    labels = { "bug", "help wanted" },
    assignees = { "octocat" },
  },
}

This get translated to gh api --method POST /repos/:owner/:repo/issues -f "title=Found a difficult bug" -f "body=Please help fix this bug" -f "labels[]=bug" -f "labels[]=help wanted" -f "assignees[]=octocat".

See a similar example here.

GraphQL API

The GraphQL API can be used in a similar manner.

For example, the request gh api graphql -f <query> --jq .data.viewer.login with the query being,

query {
  viewer {
    login
  }
}

can be run like this:

local query = [[
query {
  viewer {
    login
  }
}
]]

local opts = { 
  cb = gh.create_callback {
    success = function(login)
      vim.notify("Hello " .. login)
    end,
  }
}

gh.api.graphql {
  f = { query = query },
  jq = ".data.viewer.login",
  opts = opts,
}

Convenient query parameter

Instead of passing query to f, pass it to a designated parameter query. For example, the logic above becomes:

gh.api.graphql {
  query = query,
  jq = ".data.viewer.login",
  opts = opts,
}

Parameterized Queries

Use parameterized queries just like with the GitHub CLI. For example, gh api graphql -f <query> -F owner=pwntester -F name=octo.nvim -F states[]=OPEN -F states[]=CLOSED --jq '[ .data.repository.issues.nodes[] | {title, state, stateReason} ]' is the following:

local query = [[
query($owner: String!, $name: String!, $states: [IssueState!]) {
  repository(owner: $owner, name: $name) {
    issues(first: 10, states: $states) {
      nodes {
        title
        state
        stateReason
      }
    }
  }
}
]]

gh.api.graphql {
  query = query,
  F = {
    owner = "pwntester",
    name = "octo.nvim",
    states = { "OPEN", "CLOSED" },
  }, 
  jq = "[ .data.repository.issues.nodes[] | {title, state, stateReason} ]",
  opts = opts,
}

Tip

Use the designated fields parameter as an alternative to F.