Dashboard Configuration (`gh-dash`)

Settings for the GitHub Dashboard.

Metadata

ID: https://dlvhdr.github.io/gh-dash/configuration/gh-dash/schema.json
Type: object

JSON Schema

Definition

{
  "$id": "https://dlvhdr.github.io/gh-dash/configuration/gh-dash/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Settings for the GitHub Dashboard.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/",
  "properties": {
    "defaults": {
      "$ref": "https://dlvhdr.github.io/gh-dash/configuration/defaults/schema.json"
    },
    "issuesSections": {
      "default": [
        {
          "filters": "is:open author:@me",
          "title": "My Issues"
        },
        {
          "filters": "is:open assignee:@me",
          "title": "Assigned"
        },
        {
          "filters": "is:open involves:@me -author:@me",
          "title": "Involved"
        }
      ],
      "description": "Define sections for the dashboard's Issues view.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#issuesSections",
      "items": {
        "$ref": "https://dlvhdr.github.io/gh-dash/configuration/issue-section/schema.json"
      },
      "title": "Issue Sections",
      "type": "array"
    },
    "keybindings": {
      "description": "Define keybindings to run shell commands.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#keybindings",
      "examples": [
        {
          "issues": [
            {
              "command": "gh issue pin {{ .IssueNumber }} --repo {{ .RepoName }}",
              "key": "P"
            }
          ]
        },
        {
          "prs": [
            {
              "command": "tmux new-window -c {{.RepoPath}} '\n  gh pr checkout {{.PrNumber}} \u0026\u0026\n  nvim -c \":DiffviewOpen master...{{.HeadRefName}}\"\n'\n",
              "key": "c"
            },
            {
              "command": "cd {{.RepoPath}} \u0026\u0026 code . \u0026\u0026 gh pr checkout {{.PrNumber}}\n",
              "key": "v"
            }
          ]
        }
      ],
      "properties": {
        "issues": {
          "$ref": "https://dlvhdr.github.io/gh-dash/configuration/keybindings/issues/schema.json"
        },
        "prs": {
          "$ref": "https://dlvhdr.github.io/gh-dash/configuration/keybindings/prs/schema.json"
        }
      },
      "title": "Keybindings",
      "type": "object"
    },
    "pager": {
      "description": "Specify the pager settings to use in the dashboard.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#pager",
      "properties": {
        "diff": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "enum": [
                "less",
                "delta"
              ]
            }
          ],
          "default": "less",
          "description": "Specifies the pager to use when diffing.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#diff",
          "title": "Diff Pager",
          "type": "string"
        }
      },
      "title": "Pager",
      "type": "object"
    },
    "prSections": {
      "default": [
        {
          "filters": "is:open author:@me",
          "title": "My Pull Requests"
        },
        {
          "filters": "is:open review-requested:@me",
          "title": "Needs My Review"
        },
        {
          "filters": "is:open involves:@me -author:@me",
          "title": "Involved"
        }
      ],
      "description": "Define sections for the dashboard's PR view.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#prSections",
      "items": {
        "$ref": "https://dlvhdr.github.io/gh-dash/configuration/pr-section/schema.json"
      },
      "title": "Pull Request Sections",
      "type": "array"
    },
    "repoPaths": {
      "description": "Key-value pairs that match repositories to local file paths.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#repoPaths",
      "examples": [
        {
          "dlvhdr/*": "~/code/repos/*",
          "dlvhdr/gh-dash": "~/code/gh-dash"
        }
      ],
      "patternProperties": {
        "\\*$": {
          "description": "If the repo name (key) includes an asterisk, the path (value) must too.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#\\*$",
          "pattern": "\\*$",
          "title": "With a Wildcard",
          "type": "string"
        },
        "^[^\\*]+$": {
          "description": "If the repo name (key) doesn't include an asterisk, the path (value) can't either.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#^[^\\*]+$",
          "pattern": "^[^\\*]+$",
          "title": "Without a Wildcard",
          "type": "string"
        }
      },
      "title": "Repo Path Map",
      "type": "object"
    },
    "theme": {
      "$ref": "https://dlvhdr.github.io/gh-dash/configuration/theme/schema.json"
    }
  },
  "title": "Dashboard Configuration",
  "type": "object"
}

Pull Request Sections (`prSections`)

The prSections setting defines one or more sections to display in the dashboard’s PRs view as tabs. Each section needs a title, which is displayed as the tab name for the section, and a GitHub search filter. The dashboard queries GitHub with the search filter to populate the list of PRs to display for that section.

For more information about defining a PR section, see PR Section Options.

Metadata

Type

array

Valid items

PR Section Options (Schema)

Defines a section in the dashboard’s PRs view.

Every section must define a title and filters.

When you define limit for a section, that value overrides the defaults.prsLimit setting.

When you define layout for a section, that value overrides the defaults.layout.pr setting.

For more information, see PR Section Options.

Default Value

- filters: is:open author:@me
  title: My Pull Requests
- filters: is:open review-requested:@me
  title: Needs My Review
- filters: is:open involves:@me -author:@me
  title: Involved

By default, the PRs view on the dashboard has three sections:

The My Pull Requests section fetches open PRs authored by you.
The Needs My Review section fetches open PRs where you are a requested reviewer.
The Involved section fetches open PRs authored by someone else and that meet at least one of the following criteria:
- The PR is assigned to you.
- The PR’s body, a comment on the PR, or one of the PR’s commit messages mentions you.
- You commented on the PR.

Issue Sections (`issuesSections`)

The issueSections setting defines one or more sections to display in the dashboard’s Issues view as tabs. Each section needs a title, which is displayed as the tab name for the section, and a GitHub search filter. The dashboard queries GitHub with the search filter to populate the list of issues to display for that section.

For more information about defining an issue section, see Issue Section Options.

Metadata

Type

array

Valid items

Issue Section Options (Schema)

Defines a section in the dashboard’s Issues view.

Every section must define a title and filters.

When you define limit for a section, that value overrides the defaults.issuesLimit setting.

When you define layout for a section, that value overrides the defaults.layout.issue setting.

For more information, see Issue Section Options.

Default Value

- filters: is:open author:@me
  title: My Issues
- filters: is:open assignee:@me
  title: Assigned
- filters: is:open involves:@me -author:@me
  title: Involved

By default, the Issues view on the dashboard has three sections:

The My Issues section fetches open issues authored by you.
The Assigned section fetches open issues assigned to you.
The Involved section fetches open issues authored by someone else and that meet at least one of the following criteria:
- The issue is assigned to you.
- The issue’s body or a comment on the issue mentions you.
- You commented on the issue.

Default Options (`defaults`)

These settings define the default behavior for the dashboard. You can override many of these settings on a per-section basis.

For more information, see Default Options

Repo Path Map (`repoPaths`)

You can use the repoPaths setting to map repository names (as keys) to local paths (as values). This map coonfigures where to locate repositories when checking out PRs.

The mappings can be exact matches, like the full name or path of a repository, or wildcard matches using the owner and a partial path.

An exact match for the full repository name to a full path takes priority over a matching wildcard. Wildcard keys must match to a wildcard path.

The RepoName and RepoPath keybinding arguments are fully expanded when sent to the command.

Metadata

Type: object

Examples

Matching Repositories

dlvhdr/*: ~/code/repos/*
dlvhdr/gh-dash: ~/code/gh-dash

In this example, the first key is defined with a wildcard (*) as dlvhdr/*, so the dashboard will use this entry to resolve the path for any repo in the dlvhdr namespace, like [dlvhdr/jb] or [dlvhdr/harbor]. Note that the value for this key also uses a wildcard. If the key specifies a wildcard, the value must specify one too.

If a repository in the dlvhdr namespace has been cloned into the ~/code/repos folder, the dashboard will be able to checkout PRs for that repository locally.

If the repository isn’t found, the [checkout command] raises an error.

The second key defines an exact mapping between the dlvhdr/gh-dash repository and the ~/code/gh-dash folder. Because this is a non-wildcard mapping, the dashboard will use this value to resolve the repository path for dlvhdr/gh-dash even though there’s also an entry for dlvhdr/*.

Pattern Properties

With a Wildcard

If the key for an repoPath entry ends with a wildcard (*), its value must also have a wildcard. If a key ends with a wildcard but the value doesn’t, gh-dash won’t be able to correctly map repositories to folders.

Metadata

Type: string
Required regex pattern: \*$

Without a Wildcard

If the key for an repoPath entry doesn’t have a wildcard (*), its value must not have a wildcard. If a key ends without a wildcard but the value does, gh-dash won’t be able to correctly map repositories to folders.

Metadata

Type: string
Required regex pattern: ^[^\*]+$

Keybindings (`keybindings`)

Define your own custom keybindings to run shell commands using [Go templates]. You can define your keybindings for the PRs and Issues views separately.

Metadata

Type: object

Examples

Pin an Issue

issues:
- command: gh issue pin {{ .IssueNumber }} --repo {{ .RepoName }}
  key: P

This example binds P in the Issues view of the dashboard to the gh issue pin command to pin the selected issue in the repository.

Review PRs

prs:
- command: |
    tmux new-window -c {{.RepoPath}} '
      gh pr checkout {{.PrNumber}} &&
      nvim -c ":DiffviewOpen master...{{.HeadRefName}}"
    '    
  key: c
- command: |
    cd {{.RepoPath}} && code . && gh pr checkout {{.PrNumber}}    
  key: v

This example binds c and v in the PRs view of the dashboard to checkout the selected PR and open the repository in Neovim and VS Code respectively.

The Neovim keybinding opens the editor in another tmux window.

PRs Commands (`prs`)

Define any number of keybindings for the PRs view.

The available arguments are:

Argument	Description
`RepoName`	The full name of the repo (e.g. `dlvhdr/gh-dash`)
`RepoPath`	The path to the Repo, using the `config.yml` `repoPaths` key to get the mapping
`PrNumber`	The PR number
`HeadRefName`	The PR’s remote branch name

For more information, see PRs Commands

Issues Commands (`issues`)

Define any number of keybindings for the Issues view.

The available arguments are:

Argument	Description
`RepoName`	The full name of the repo (e.g. `dlvhdr/gh-dash`)
`RepoPath`	The path to the Repo, using the `config.yml` `repoPaths` key to get the mapping
`IssueNumber`	The Issue number

For more information, see Issues Commands

Theme Options (`theme`)

This setting defines the dashboard’s theme. It only effects the presentation of the dashboard, not the data. Currently, the theme only defines colors. To control how table columns and preview pane display for the views, use the defaults, prSections, and issueSections settings.

The default colors for the theme in the schema are for dark mode terminals. The dashboard actually has different defaults for light mode terminals, but the schema can’t represent a dynamic default. The informational text for each color also enumerates the light mode color.

To define any color for your dashboard, you must define every color. All properties are required properties. Every color for the dashboard’s theme must be a valid hex color, like #a3c or #aa33cc.

To find hex colors to use in your dashboard, visit color-hex.com. You can browse colors, inspect a given color, get alternate shades and tints for a color, derive a color palette, and more.

For more information, see Theme Options

JSON Schema

Pull Request Sections (prSections)

Default Value

Issue Sections (issuesSections)

Default Value

Default Options (defaults)

Examples

Matching Repositories

Pattern Properties

With a Wildcard

Without a Wildcard

Examples

Pin an Issue

Review PRs

PRs Commands (prs)

Issues Commands (issues)

Theme Options (theme)

Diff Pager (diff)

Pull Request Sections (`prSections`)

Issue Sections (`issuesSections`)

Default Options (`defaults`)

PRs Commands (`prs`)

Issues Commands (`issues`)

Theme Options (`theme`)

Diff Pager (`diff`)