60af6bcb49
These changes work to improve GitHub CLI users experience by bringing: - clarity between official and unofficial installation methods - insight into unofficial installation methods - consistency across supported operating systems
118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
# GitHub CLI
|
|
|
|
`gh` is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with `git` and your code.
|
|
|
|
|
|
|
|
GitHub CLI is supported for users on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server 2.20+ with support for macOS, Windows, and Linux.
|
|
|
|
## Documentation
|
|
|
|
For [installation options see below](#installation), for usage instructions [see the manual]( https://cli.github.com/manual/).
|
|
|
|
## Contributing
|
|
|
|
If anything feels off or if you feel that some functionality is missing, please check out the [contributing page](.github/CONTRIBUTING.md). There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.
|
|
|
|
If you are a hubber and are interested in shipping new commands for the CLI, check out our [doc on internal contributions](docs/working-with-us.md)
|
|
|
|
<!-- this anchor is linked to from elsewhere, so avoid renaming it -->
|
|
## Installation
|
|
|
|
### [macOS](docs/install_macos.md)
|
|
|
|
#### [Recommended _(Official)_](docs/install_macos.md#recommended-official)
|
|
|
|
- [Homebrew](docs/install_macos.md#homebrew)
|
|
- [Precompiled binaries](docs/install_macos.md#precompiled-binaries) on [releases page][]
|
|
|
|
#### [Community _(Unofficial)_](docs/install_macos.md#community-unofficial)
|
|
|
|
- Package managers: [Conda](docs/install_macos.md#conda), [Flox](docs/install_macos.md#flox), [MacPorts](docs/install_macos.md#macports), [Spack](docs/install_macos.md#spack), [Webi](docs/install_macos.md#webi)
|
|
|
|
### [Linux & Unix](docs/install_linux.md)
|
|
|
|
#### [Recommended _(Official)_](docs/install_linux.md#recommended-official)
|
|
|
|
- [Debian, Raspberry Pi, Ubuntu](docs/install_linux.md#debian)
|
|
- [Amazon Linux, CentOS, Fedora, openSUSE, RHEL, SUSE](docs/install_linux.md#rpm)
|
|
- [Precompiled binaries](docs/install_linux.md#precompiled-binaries) on [releases page][]
|
|
|
|
#### [Community _(Unofficial)_](docs/install_linux.md#community-unofficial)
|
|
|
|
- Package managers: [Conda](docs/install_linux.md#conda), [Flox](docs/install_linux.md#flox), [Spack](docs/install_linux.md#spack), [Webi](docs/install_linux.md#webi)
|
|
- Operating systems: [Alpine Linux](docs/install_linux.md#alpine-linux), [Android](docs/install_linux.md#android), [Arch Linux](docs/install_linux.md#arch-linux), [Fedora Community](docs/install_linux.md#fedora-community), [FreeBSD](docs/install_linux.md#freebsd), [Funtoo](docs/install_linux.md#funtoo), [Gentoo](docs/install_linux.md#gentoo), [Manjaro Linux](docs/install_linux.md#manjaro-linux), [MidnightBSD](docs/install_linux.md#midnightbsd), [NetBSD/pkgsrc](docs/install_linux.md#netbsdpkgsrc), [Nix/NixOS](docs/install_linux.md#nixnixos), [OpenBSD](docs/install_linux.md#openbsd), [openSUSE Tumbleweed](docs/install_linux.md#opensuse-tumbleweed), [Solus Linux](docs/install_linux.md#solus-linux), [Void Linux](docs/install_linux.md#void-linux).
|
|
|
|
### [Windows](docs/install_windows.md)
|
|
|
|
#### [Recommended _(Official)_](docs/install_windows.md#recommended-official)
|
|
|
|
- [WinGet](docs/install_windows.md#winget)
|
|
- [Precompiled binaries](docs/install_windows.md#precompiled-binaries) on [releases page][]
|
|
|
|
#### [Community _(Unofficial)_](docs/install_windows.md#community-unofficial)
|
|
|
|
- Package managers: [Chocolatey](docs/install_windows.md#chocolatey), [Conda](docs/install_windows.md#conda), [Scoop](docs/install_windows.md#scoop), [Webi](docs/install_windows.md#webi)
|
|
|
|
### Build from source
|
|
|
|
See here on how to [build GitHub CLI from source](docs/install_source.md).
|
|
|
|
### GitHub Codespaces
|
|
|
|
To add GitHub CLI to your codespace, add the following to your [devcontainer file](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-features-to-a-devcontainer-file):
|
|
|
|
```json
|
|
"features": {
|
|
"ghcr.io/devcontainers/features/github-cli:1": {}
|
|
}
|
|
```
|
|
|
|
### GitHub Actions
|
|
|
|
[GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) have the GitHub CLI pre-installed, which is updated weekly.
|
|
|
|
If a specific version is needed, your GitHub Actions workflow will need to install it based on the [macOS](#macos), [Linux & Unix](#linux--unix), or [Windows](#windows) instructions above.
|
|
|
|
For information on all pre-installed tools, see [`actions/runner-images`](https://github.com/actions/runner-images)
|
|
|
|
### Verification of binaries
|
|
|
|
Since version 2.50.0, `gh` has been producing [Build Provenance Attestation](https://github.blog/changelog/2024-06-25-artifact-attestations-is-generally-available/), enabling a cryptographically verifiable paper-trail back to the origin GitHub repository, git revision, and build instructions used. The build provenance attestations are signed and rely on Public Good [Sigstore](https://www.sigstore.dev/) for PKI.
|
|
|
|
There are two common ways to verify a downloaded release, depending on whether `gh` is already installed or not. If `gh` is installed, it's trivial to verify a new release:
|
|
|
|
- **Option 1: Using `gh` if already installed:**
|
|
|
|
```shell
|
|
$ gh at verify -R cli/cli gh_2.62.0_macOS_arm64.zip
|
|
Loaded digest sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc for file://gh_2.62.0_macOS_arm64.zip
|
|
Loaded 1 attestation from GitHub API
|
|
✓ Verification succeeded!
|
|
|
|
sha256:fdb77f31b8a6dd23c3fd858758d692a45f7fc76383e37d475bdcae038df92afc was attested by:
|
|
REPO PREDICATE_TYPE WORKFLOW
|
|
cli/cli https://slsa.dev/provenance/v1 .github/workflows/deployment.yml@refs/heads/trunk
|
|
```
|
|
|
|
- **Option 2: Using Sigstore [`cosign`](https://github.com/sigstore/cosign):**
|
|
|
|
To perform this, download the [attestation](https://github.com/cli/cli/attestations) for the downloaded release and use cosign to verify the authenticity of the downloaded release:
|
|
|
|
```shell
|
|
$ cosign verify-blob-attestation --bundle cli-cli-attestation-3120304.sigstore.json \
|
|
--new-bundle-format \
|
|
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
|
|
--certificate-identity="https://github.com/cli/cli/.github/workflows/deployment.yml@refs/heads/trunk" \
|
|
gh_2.62.0_macOS_arm64.zip
|
|
Verified OK
|
|
```
|
|
|
|
## Comparison with hub
|
|
|
|
For many years, [hub](https://github.com/github/hub) was the unofficial GitHub CLI tool. `gh` is a new project that helps us explore
|
|
what an official GitHub CLI tool can look like with a fundamentally different design. While both
|
|
tools bring GitHub to the terminal, `hub` behaves as a proxy to `git`, and `gh` is a standalone
|
|
tool. Check out our [more detailed explanation](docs/gh-vs-hub.md) to learn more.
|
|
|
|
[releases page]: https://github.com/cli/cli/releases/latest
|