Skip to content

Commit 8d9ba66

Browse files
kevinwang5658github-actions[bot]
kevinwang5658
authored and
github-actions[bot]
committed
feat: Add github-cli resource (auto-generated from issue #32)
1 parent 66f372a commit 8d9ba66

8 files changed

Lines changed: 912 additions & 0 deletions

File tree

‎docs/resources/(resources)/github-cli.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: github-cli
3+
description: Reference pages for the GitHub CLI (gh) resources
4+
---
5+
6+
The GitHub CLI resources install and configure the [GitHub CLI (`gh`)](https://cli.github.com/manual/) tool. Four resources are provided to manage distinct concerns: installation and global configuration, authentication, command aliases, and GitHub account SSH keys.
7+
8+
---
9+
10+
## github-cli
11+
12+
Installs `gh` and manages global configuration settings such as the default git protocol, editor, pager, and browser.
13+
14+
### Parameters
15+
16+
- **gitProtocol**: *(string: `https` | `ssh`)* Default protocol for git operations. Defaults to `https`.
17+
- **editor**: *(string)* Default text editor for gh commands (e.g. `vim`, `nano`, `code --wait`).
18+
- **prompt**: *(string: `enabled` | `disabled`)* Whether interactive prompts are shown. Defaults to `enabled`.
19+
- **pager**: *(string)* Pager program used to display long output (e.g. `less`).
20+
- **browser**: *(string)* Default browser to open URLs (e.g. `firefox`).
21+
22+
### Example usage
23+
24+
```json title="codify.jsonc"
25+
[
26+
{
27+
"type": "github-cli",
28+
"gitProtocol": "ssh",
29+
"editor": "vim"
30+
}
31+
]
32+
```
33+
34+
---
35+
36+
## github-cli-auth
37+
38+
Authenticates the GitHub CLI using a Personal Access Token (PAT). Supports multiple accounts and GitHub Enterprise Server hostnames.
39+
40+
> **Security note:** The `token` field is marked sensitive and is never logged or displayed by Codify. Store PATs in a secrets manager and reference them via environment variables where possible.
41+
42+
### Parameters
43+
44+
- **token** *(required)*: *(string)* GitHub personal access token (classic or fine-grained).
45+
- **hostname**: *(string)* GitHub hostname. Defaults to `github.com`. Set to your GHE hostname (e.g. `github.mycompany.com`) for enterprise instances.
46+
47+
### Example usage
48+
49+
```json title="codify.jsonc"
50+
[
51+
{
52+
"type": "github-cli",
53+
"gitProtocol": "https"
54+
},
55+
{
56+
"type": "github-cli-auth",
57+
"token": "<Replace me here!>"
58+
}
59+
]
60+
```
61+
62+
---
63+
64+
## github-cli-alias
65+
66+
Creates a short-hand alias for a `gh` command. Each alias is an independent resource, identified by its name.
67+
68+
### Parameters
69+
70+
- **alias** *(required)*: *(string)* The alias name used to invoke the command (e.g. `prc`).
71+
- **expansion** *(required)*: *(string)* The gh command or shell command this alias expands to (e.g. `pr create`).
72+
- **shell**: *(boolean)* When `true`, the expansion is executed as a shell command via `sh`, enabling pipes, redirects, and other shell features. Defaults to `false`.
73+
74+
### Example usage
75+
76+
```json title="codify.jsonc"
77+
[
78+
{
79+
"type": "github-cli-alias",
80+
"alias": "prc",
81+
"expansion": "pr create"
82+
},
83+
{
84+
"type": "github-cli-alias",
85+
"alias": "prs",
86+
"expansion": "pr status"
87+
}
88+
]
89+
```
90+
91+
---
92+
93+
## github-cli-ssh-key
94+
95+
Uploads a local SSH public key to your GitHub account. This is distinct from the `ssh-key` resource, which manages local key files — this resource registers an existing key with GitHub via the `gh ssh-key add` command.
96+
97+
Requires authentication (`github-cli-auth`) to be configured.
98+
99+
### Parameters
100+
101+
- **title** *(required)*: *(string)* Display name for the key on GitHub (e.g. `My Laptop`).
102+
- **keyFile** *(required)*: *(string)* Path to the local SSH public key file (e.g. `~/.ssh/id_ed25519.pub`).
103+
- **keyType**: *(string: `authentication` | `signing`)* Key usage type. Use `authentication` (default) for git over SSH, or `signing` for commit signing.
104+
105+
### Example usage
106+
107+
```json title="codify.jsonc"
108+
[
109+
{
110+
"type": "github-cli"
111+
},
112+
{
113+
"type": "github-cli-auth",
114+
"token": "<Replace me here!>"
115+
},
116+
{
117+
"type": "github-cli-ssh-key",
118+
"title": "My Laptop",
119+
"keyFile": "~/.ssh/id_ed25519.pub",
120+
"keyType": "authentication"
121+
}
122+
]
123+
```

‎src/index.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ import { DnfResource } from './resources/dnf/dnf.js';
1010
import { DockerResource } from './resources/docker/docker.js';
1111
import { FileResource } from './resources/file/file.js';
1212
import { RemoteFileResource } from './resources/file/remote-file.js';
13+
import { GithubCliResource } from './resources/github-cli/github-cli.js';
14+
import { GithubCliAuthResource } from './resources/github-cli/github-cli-auth.js';
15+
import { GithubCliAliasResource } from './resources/github-cli/github-cli-alias.js';
16+
import { GithubCliSshKeyResource } from './resources/github-cli/github-cli-ssh-key.js';
1317
import { GitResource } from './resources/git/git/git-resource.js';
1418
import { GitLfsResource } from './resources/git/lfs/git-lfs.js';
1519
import { GitRepositoriesResource } from './resources/git/repositories/git-repositories.js';
@@ -109,6 +113,10 @@ runPlugin(Plugin.create(
109113
new SyncthingDeviceResource(),
110114
new SyncthingFolderResource(),
111115
new RbenvResource(),
116+
new GithubCliResource(),
117+
new GithubCliAuthResource(),
118+
new GithubCliAliasResource(),
119+
new GithubCliSshKeyResource(),
112120
],
113121
{ minSupportedCliVersion: MIN_SUPPORTED_CLI_VERSION }
114122
))

‎src/resources/github-cli/examples.ts‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
import { ExampleConfig } from '@codifycli/plugin-core';
2+
3+
export const exampleGithubCliBasic: ExampleConfig = {
4+
title: 'Install GitHub CLI with SSH configuration',
5+
description: 'Install gh and configure it to use SSH for git operations and vim as the default editor.',
6+
configs: [
7+
{
8+
type: 'github-cli',
9+
gitProtocol: 'ssh',
10+
editor: 'vim',
11+
},
12+
],
13+
};
14+
15+
export const exampleGithubCliFull: ExampleConfig = {
16+
title: 'Full GitHub CLI setup with authentication',
17+
description: 'Install gh, authenticate with a personal access token, and configure SSH as the default git protocol.',
18+
configs: [
19+
{
20+
type: 'github-cli',
21+
gitProtocol: 'ssh',
22+
},
23+
{
24+
type: 'github-cli-auth',
25+
token: '<Replace me here!>',
26+
},
27+
],
28+
};
29+
30+
export const exampleGithubCliAuthBasic: ExampleConfig = {
31+
title: 'Authenticate GitHub CLI with a token',
32+
description: 'Log in to GitHub using a personal access token for non-interactive environments.',
33+
configs: [
34+
{
35+
type: 'github-cli-auth',
36+
token: '<Replace me here!>',
37+
},
38+
],
39+
};
40+
41+
export const exampleGithubCliAuthEnterprise: ExampleConfig = {
42+
title: 'Authenticate to GitHub Enterprise',
43+
description: 'Log in to a self-hosted GitHub Enterprise Server instance with a PAT.',
44+
configs: [
45+
{
46+
type: 'github-cli',
47+
},
48+
{
49+
type: 'github-cli-auth',
50+
token: '<Replace me here!>',
51+
hostname: 'github.mycompany.com',
52+
},
53+
],
54+
};
55+
56+
export const exampleGithubCliAliasBasic: ExampleConfig = {
57+
title: 'Add a gh CLI alias',
58+
description: 'Create a short alias "prc" that expands to "pr create" for faster pull request creation.',
59+
configs: [
60+
{
61+
type: 'github-cli-alias',
62+
alias: 'prc',
63+
expansion: 'pr create',
64+
},
65+
],
66+
};
67+
68+
export const exampleGithubCliAliasShell: ExampleConfig = {
69+
title: 'Full GitHub CLI setup with aliases',
70+
description: 'Install gh, authenticate, and set up handy aliases for common workflows.',
71+
configs: [
72+
{
73+
type: 'github-cli',
74+
},
75+
{
76+
type: 'github-cli-auth',
77+
token: '<Replace me here!>',
78+
},
79+
{
80+
type: 'github-cli-alias',
81+
alias: 'prc',
82+
expansion: 'pr create',
83+
},
84+
{
85+
type: 'github-cli-alias',
86+
alias: 'prs',
87+
expansion: 'pr status',
88+
},
89+
],
90+
};
91+
92+
export const exampleGithubCliSshKeyBasic: ExampleConfig = {
93+
title: 'Upload SSH key to GitHub',
94+
description: 'Register an existing local SSH public key with your GitHub account for authentication.',
95+
configs: [
96+
{
97+
type: 'github-cli-ssh-key',
98+
title: 'My Laptop',
99+
keyFile: '~/.ssh/id_ed25519.pub',
100+
},
101+
],
102+
};
103+
104+
export const exampleGithubCliSshKeyFull: ExampleConfig = {
105+
title: 'Full SSH key setup for GitHub',
106+
description: 'Install gh, authenticate, then upload a local SSH key to your GitHub account.',
107+
configs: [
108+
{
109+
type: 'github-cli',
110+
},
111+
{
112+
type: 'github-cli-auth',
113+
token: '<Replace me here!>',
114+
},
115+
{
116+
type: 'github-cli-ssh-key',
117+
title: 'My Laptop',
118+
keyFile: '~/.ssh/id_ed25519.pub',
119+
keyType: 'authentication',
120+
},
121+
],
122+
};

0 commit comments

Comments
 (0)