nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-05 17:45:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: shorten the gt guides

Browse Source 
Cover what users need to get going and leave the details to
gt <command> --help and gt help.

Signed-off-by: bircni <[email protected]>
This commit is contained in:
bircni committed 2026-10-22 18:34:04 +02:00
1 parent 540757fe56
commit 31cd47a65c
5 files changed
+72 -450
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

cli-docs/authentication.md
+27 -152
View File
@@ -4,179 +4,54 @@ sidebar_position: 3
# Logging in
`gt auth login` logs in to a Gitea instance. gt can authenticate in three ways:
On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.
| Method | Flag | Best for |
| --- | --- | --- |
| OAuth in a web browser | `--oauth` | Interactive use, instances with single sign-on or two-factor authentication |
| Access token | `--with-token` | Any instance, machines without a browser |
| SSH key signing | `--ssh-key`, `--ssh-agent-key`, `--ssh-agent-principal` | Using an SSH key you already have instead of a token |
gt never asks for your password. On a terminal, `gt auth login` without a method flag asks
for the instance, how to log in, where to keep the token, and whether Git should use gt
for the instance:
```bash
gt auth login
```
## OAuth
## OAuth in a browser
```bash
gt auth login --host https://gitea.example.com --oauth
```
gt opens the instance's authorization page in your browser, or prints its URL when no
browser opens. You sign in there as you do on the web, so single sign-on through an
external identity provider and two-factor authentication work unchanged. gt listens on
`127.0.0.1` for the answer, so the browser has to run on the same machine as gt. OAuth
needs this interaction and is refused with `--no-input`.
gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.
By default the token has write access to everything but administration. `--scopes`
requests fewer, using the [token scope](/development/oauth2-provider#scopes) names:
## Access token
Create a token under **Settings > Applications** on the instance and pass it on stdin:
```bash
gt auth login --host https://gitea.example.com --oauth --scopes read:repository,read:user
gt auth login --host https://gitea.example.com --with-token < token.txt
```
gt refreshes an expiring OAuth token on its own. `gt auth refresh` refreshes it now.
The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.
gt uses the OAuth application that Gitea registers by default for its command line
client, listed as `tea` in [`DEFAULT_APPLICATIONS`](/administration/config-cheat-sheet#oauth2-oauth2).
If an administrator turned it off, register an OAuth2 application that is not a
confidential client, with the redirect URI `http://127.0.0.1`, and pass its client ID with
`--client-id`. gt remembers the ID for the instance.
## SSH key
## Access tokens
1. Sign in to the instance in a web browser, with single sign-on or two-factor
authentication if the instance uses them.
2. Under **Settings > Applications**, create an access token with the scopes you need.
3. Save the token in a private file and log in with it:
```bash
gt auth login --host https://gitea.example.com --with-token < token.txt
```
On a terminal, `--with-token` without input asks for the token instead.
gt needs `read:user` to find out which account a token belongs to. Add the scopes of the
commands you use:
| Scope | Commands |
| --- | --- |
| `repository` | `repo`, `pr`, `release`, `branch`, `run`, `workflow`, `secret` and `variable` of a repository, `webhook`, `wiki` |
| `issue` | `issue`, `label`, `milestone`, `time`, and comments on pull requests |
| `organization` | `org`, `team`, and `secret`, `variable` and `webhook` with `--org` |
| `notification` | `notification` |
| `package` | `package` |
| `user` | `ssh-key`, and `secret` and `variable` with `--account` |
| `admin` | `admin` |
Choose `write:` for the commands that change something, `read:` for the ones that only
read. Gitea counts pull request comments, labels and milestones as issue operations, so
working with pull requests usually needs both `write:repository` and `write:issue`. The
[scopes table](/development/oauth2-provider#scopes) describes each scope.
A token pasted with `--with-token` cannot be refreshed. When it expires or is revoked, log
in again.
## Where credentials are kept
gt keeps the instances and accounts in `hosts.yml` and its preferences in `config.yml`, in
its configuration directory. `gt config path` prints both files; `GITEA_CLI_CONFIG_DIR`
moves the directory.
Tokens are not written to these files. `--credential-store` chooses where they go:
- `keyring` (default): the system keyring, such as the macOS Keychain, the Windows
Credential Manager, or the Secret Service on Linux. When no keyring is available, the
login fails rather than falling back to a file.
- `file`: a `credentials` directory in the configuration directory that only your user
can read. Use it where no keyring exists, such as in a container or over SSH.
A token given in `GITEA_TOKEN` is never stored. See [Using gt in CI](ci.md).
`gt auth status` shows the accounts on each instance, the active one, and how each
authenticates; `gt auth status --verify` checks every credential against its instance.
`gt auth token` prints the token of the active account, for scripts that call the API
themselves. `gt auth logout` forgets an account and deletes its stored credential.
## SSH keys
Instead of a token, gt can sign each API request with an SSH key that is registered for
your account on the instance:
gt can sign its requests with an SSH key registered for your account instead of using a
token:
```bash
gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
```
When a certificate (`id_ed25519-cert.pub`) is next to the key, gt signs with the
certificate. gt asks for the passphrase of an encrypted key. To sign with a key held by
`ssh-agent`, pass its fingerprint with `--ssh-agent-key`; to sign with an agent
certificate, pass its principal with `--ssh-agent-principal`. Accounts that sign requests
have no token, so `gt auth token` has nothing to print for them.
## Where credentials are kept
Tokens go to the system keyring by default. `--credential-store file` keeps them in gt's
configuration directory instead, for machines without a keyring. `gt auth status` lists
your accounts and `gt auth logout` removes one.
## Git over HTTPS
gt's own clone and checkout commands authenticate without any setup. For `git push` and
`git fetch` over HTTPS, let Git ask gt for credentials:
```bash
gt auth setup-git
gt auth setup-git --host gitea.example.com
# only for the current repository, always as alice
gt auth setup-git --local --user alice
```
Git then uses the active account of the instance, or the account of `--user`. Other
credential helpers, such as a system keychain, are turned off for the instance, since they
would answer first and keep a copy of gt's token; `--keep-helpers` keeps them.
`gt auth login` on a terminal offers to do this for you.
`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.
## Several instances and accounts
Run `gt auth login` once per instance and account. Commands pick the instance from the
repository's Git remote, `--host`, `GITEA_CLI_HOST`, the `default_host` setting, or the only
instance you are logged in to; `gt help environment` gives the full order.
Each instance has one active account. `gt auth switch` changes it: with two accounts it
toggles between them, with more it asks which one. `--user`, or `GITEA_CLI_USER`, uses
another account for a single command:
```bash
gt auth switch bob --host gitea.example.com
gt issue list --user alice
```
To use another instance by default outside a clone:
```bash
gt config set default_host https://gitea.example.com
```
## Access proxies and client certificates
An instance behind an access proxy may need extra headers or a TLS client certificate.
`--header` sends a header with every request to the instance; a value of `$NAME` or
`${NAME}` is read from that environment variable each time, so the secret stays out of
gt's files:
```bash
gt auth login --host https://gitea.example.com --with-token \
--header 'CF-Access-Client-Id: $CF_ID' \
--header 'CF-Access-Client-Secret: $CF_SECRET' < token.txt
```
`--client-cert` presents a PEM client certificate, and `--client-key` names its
unencrypted PEM key when the key is not in the certificate file. Convert a PKCS#12 file
with:
```bash
openssl pkcs12 -in cert.p12 -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.p12 -nocerts -nodes -out key.pem
```
gt keeps these per instance; `gt config set headers`, `client_cert` and `client_key` with
`--host` change them later. `--insecure` skips TLS certificate verification for an
instance, for testing only.
Run `gt auth login` for each instance and account. gt picks the instance from the
repository's remote or `--host`, and the account with `gt auth switch` or `--user`.
For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate; see `gt auth login --help`.