Split references into focused files, trim SKILL.md, update README
This commit is contained in:
16 files changed
+1215
-1144
No files matched your search
@@ -7,19 +7,12 @@ releases, Actions, packages, organizations, and authentication.
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# HTTPS
|
||||
npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git
|
||||
|
||||
# SSH
|
||||
npx skills add ssh://git@gitea.kosmos.org/raucao/gitea-gt-cli.git
|
||||
|
||||
# Specific agent / global
|
||||
npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git -a claude-code -g
|
||||
npx skills add https://gitea.kosmos.org/raucao/gitea-gt-cli.git -a opencode -g
|
||||
```
|
||||
|
||||
The `skills` CLI supports any git host, so this works from Gitea. It will not be
|
||||
listed on skills.sh, which only indexes GitHub repositories.
|
||||
|
||||
Without the `skills` CLI, copy `skills/gitea-gt-cli/` into your agent's skills
|
||||
directory, for example `~/.agents/skills/gitea-gt-cli/` or
|
||||
`.agents/skills/gitea-gt-cli/`.
|
||||
@@ -28,14 +21,22 @@ directory, for example `~/.agents/skills/gitea-gt-cli/` or
|
||||
|
||||
```text
|
||||
skills/gitea-gt-cli/
|
||||
├── SKILL.md # when to use gt, auth, core concepts, workflows, gotchas
|
||||
├── SKILL.md # when to use gt, auth, core concepts, command map, gotchas
|
||||
└── references/
|
||||
├── commands-core.md # auth, repo, issue, pr, release, org, label, milestone, branch
|
||||
├── commands-actions.md # run, workflow, secret, variable, package, admin
|
||||
└── commands-misc.md # team, notification, search, status, time, webhook, wiki, ...
|
||||
├── workflows.md # end-to-end recipes (issues, PRs, Actions, releases, fork/sync)
|
||||
├── auth.md # auth, doctor, setup-git, env vars
|
||||
├── repos.md # repo, branch
|
||||
├── issues.md # issue, label, milestone
|
||||
├── pull-requests.md # pr (reviews, checks, diff, merge, status)
|
||||
├── releases.md # release
|
||||
├── organizations.md # org, team
|
||||
├── actions.md # run, workflow
|
||||
├── ci-config.md # secret, variable, package
|
||||
├── discovery.md # search, status, notification, time
|
||||
└── instance.md # config, api, alias, completion, webhook, wiki, ssh-key, admin
|
||||
```
|
||||
|
||||
`SKILL.md` stays small and points at the reference file for each command group,
|
||||
`SKILL.md` stays small and maps each command group to a focused reference file,
|
||||
so the agent loads only the detail it needs.
|
||||
|
||||
## Requirements
|
||||
|
||||
+29
-110
@@ -23,8 +23,8 @@ at your desk and in CI.
|
||||
which is stable; text output is for people.
|
||||
|
||||
Use this skill whenever a task involves running `gt` or managing a Gitea
|
||||
instance from the shell. Do not guess flags: every command's help lists its
|
||||
flags and JSON fields, and the reference files below mirror that help.
|
||||
instance from the shell. Do not guess flags: each command's help lists its flags
|
||||
and JSON fields, and the reference files mirror that help.
|
||||
|
||||
## Install `gt`
|
||||
|
||||
@@ -35,9 +35,6 @@ curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
|
||||
# Windows (PowerShell)
|
||||
irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
|
||||
|
||||
# Docker
|
||||
docker run --rm gitea/gitea-cli --help
|
||||
|
||||
# From source
|
||||
go install gitea.dev/cli/cmd/gt@latest
|
||||
```
|
||||
@@ -47,38 +44,21 @@ Verify with `gt version`. Binaries are also at
|
||||
|
||||
## Authenticate
|
||||
|
||||
`gt` keeps accounts in `hosts.yml` and tokens in the system keyring (or a
|
||||
private file), under `~/.config/gitea-cli/` (`GITEA_CLI_CONFIG_DIR` overrides).
|
||||
It never reads `tea`'s config.
|
||||
`gt` stores accounts in `hosts.yml` and tokens in the system keyring (or a
|
||||
private file), under `~/.config/gitea-cli/`. It never reads `tea`'s config.
|
||||
|
||||
```bash
|
||||
# Interactive: asks for instance, OAuth or token, storage, and git setup
|
||||
gt auth login
|
||||
|
||||
# CI / non-interactive: token on stdin
|
||||
gt auth login --host gitea.example.com --with-token < token.txt
|
||||
gt auth login # interactive: OAuth or token
|
||||
gt auth login --host gitea.example.com --with-token < token.txt # CI
|
||||
echo "$TOKEN" | gt auth login --host gitea.example.com --with-token
|
||||
|
||||
# OAuth in the browser with explicit scopes
|
||||
gt auth login --host gitea.example.com --oauth --scopes read:repository,read:user
|
||||
|
||||
# Inspect and use accounts
|
||||
gt auth status # which accounts, active one, method (exit 4 if none/invalid)
|
||||
gt auth status --verify # check credentials against the instance
|
||||
gt auth token # print the active token (for curl/scripts)
|
||||
gt auth switch # change the active account of an instance
|
||||
gt auth setup-git # configure git to use gt for https push/fetch
|
||||
gt doctor # diagnose settings, instance, account, repo and git
|
||||
gt auth status --verify # check the active credential
|
||||
gt doctor # diagnose the setup here
|
||||
```
|
||||
|
||||
### Environment variables (CI)
|
||||
|
||||
- `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`): use a token
|
||||
instead of stored credentials.
|
||||
- `GITEA_CLI_*` prefixed variables mirror global flags and settings; see
|
||||
`gt help environment` for the full list (config dir, user, repo, editor,
|
||||
pager, color, http timeout, ...).
|
||||
- `GITEA_INSTANCE_INSECURE`, `GITEA_INSTANCE_SSH_HOST`: pair with `GITEA_TOKEN`.
|
||||
In CI, `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`) replace stored
|
||||
credentials; other `GITEA_CLI_*` variables mirror flags and settings. Full flags,
|
||||
`setup-git`, `token`, and the environment list are in
|
||||
[references/auth.md](references/auth.md).
|
||||
|
||||
## Core concepts
|
||||
|
||||
@@ -94,12 +74,6 @@ It picks the **repository** from: `--repo`/`-R OWNER/REPO`, `GITEA_CLI_REPO`,
|
||||
remote, upstream, or origin). Like `gh`, a clone with `upstream` and `origin`
|
||||
targets `upstream`.
|
||||
|
||||
```bash
|
||||
gt -R alice/project issue list
|
||||
gt issue list --repo alice/project # same, flag after the command
|
||||
gt repo set-default upstream/name # make this clone target the upstream
|
||||
```
|
||||
|
||||
### Global flags
|
||||
|
||||
Work with every command, before or after the command name:
|
||||
@@ -117,6 +91,9 @@ Work with every command, before or after the command name:
|
||||
| `--debug` | Log HTTP method, URL, status, duration to stderr |
|
||||
| `--cwd dir` / `--remote remote` | Repository discovery |
|
||||
|
||||
Repository-scoped groups also inherit `--remote`, `--cwd`; list/view commands
|
||||
add `--json`/`--jq`. See `gt help environment`.
|
||||
|
||||
### JSON output
|
||||
|
||||
Text output is for people and may change; **use `--json` in scripts**. `--jq`
|
||||
@@ -125,8 +102,6 @@ available ones, and each command's help lists its JSON fields.
|
||||
|
||||
```bash
|
||||
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
|
||||
gt pr list --json number,title,head --jq '.[] | select(.head == "feature/login")'
|
||||
gt run list --since 24h --json id,status,conclusion,workflow
|
||||
```
|
||||
|
||||
Some fields cost extra requests (e.g. `pr list` reviewers, `issue view`
|
||||
@@ -149,78 +124,22 @@ Commands may document further codes. See `gt help exit-codes`.
|
||||
|
||||
## Command map
|
||||
|
||||
Read the reference file for a group to get its per-command flags, arguments,
|
||||
`--json` fields and examples. `gt <group> <cmd> --help` is always authoritative.
|
||||
|
||||
| Group | Commands | Reference |
|
||||
| --- | --- | --- |
|
||||
| Auth | `auth` (login, logout, refresh, setup-git, status, switch, token) | `references/commands-core.md` |
|
||||
| Repositories | `repo` (create, clone, fork, sync, view, list, edit, migrate, deploy-key, ...) | `references/commands-core.md` |
|
||||
| Issues | `issue` (create, list, view, edit, close, reopen, comment, timeline, attachment) | `references/commands-core.md` |
|
||||
| Pull requests | `pr` (create, list, view, checkout, diff, checks, review, merge, status, clean) | `references/commands-core.md` |
|
||||
| Releases | `release` (create, list, view, edit, upload, download, asset, publish) | `references/commands-core.md` |
|
||||
| Orgs & labels | `org`, `label`, `milestone`, `branch` | `references/commands-core.md` |
|
||||
| Actions | `run`, `workflow`, `secret`, `variable`, `package`, `admin` | `references/commands-actions.md` |
|
||||
| Everything else | `team`, `notification`, `search`, `status`, `time`, `webhook`, `wiki`, `ssh-key`, `api`, `config`, `alias`, `completion` | `references/commands-misc.md` |
|
||||
|
||||
**Read the reference file** when you need exact flags, arguments, accepted
|
||||
`--json` fields, or examples for a command. `gt <group> <cmd> --help` is always
|
||||
authoritative for the installed version.
|
||||
|
||||
## Common workflows
|
||||
|
||||
### Issue lifecycle
|
||||
|
||||
```bash
|
||||
gt issue list --assignee @me --state open
|
||||
gt issue view 12 --comments
|
||||
gt issue create --title "Crash on start" --body "Steps..." --label bug --milestone v1.0
|
||||
gt issue edit 12 --add-label triage --add-assignee @me
|
||||
gt issue comment 12 --body "Fixed in #14"
|
||||
gt issue close 12 --comment "Done in #14"
|
||||
```
|
||||
|
||||
### Pull requests (create → checks → review → merge)
|
||||
|
||||
```bash
|
||||
gt pr create --fill # push branch, open PR, title/body from commits
|
||||
gt pr create --fill --yes # non-interactive: also push without asking
|
||||
gt pr list --author @me --state all
|
||||
gt pr checkout 13 --update # local branch tracking the PR head
|
||||
gt pr diff 13 | git apply # pipe clean diff (git apply works)
|
||||
gt pr checks 13 --watch # waits; exit 8 while pending, 1 if a check failed
|
||||
gt pr review --approve
|
||||
gt pr review 13 --request-changes -b "Please hash the password"
|
||||
gt pr merge 13 --squash --delete-branch
|
||||
```
|
||||
|
||||
### Actions: run, watch, logs, artifacts
|
||||
|
||||
```bash
|
||||
gt workflow list
|
||||
gt workflow run deploy.yml --ref main --field env=staging
|
||||
gt run list --workflow CI --branch main --status failure
|
||||
gt run watch 34 --timeout 10m && echo deployed
|
||||
gt run view 34 --log
|
||||
gt run logs 34 --job build --follow
|
||||
gt run download 34 --name build --dir dist
|
||||
gt secret set DEPLOY_TOKEN
|
||||
```
|
||||
|
||||
### Releases
|
||||
|
||||
```bash
|
||||
gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md
|
||||
gt release list
|
||||
gt release upload v1.0.0 dist/tool-darwin --clobber
|
||||
gt release download v1.0.0
|
||||
```
|
||||
|
||||
### Fork / clone / keep in sync
|
||||
|
||||
```bash
|
||||
gt repo fork --remote # inside a clone: add fork as origin, rename old origin to upstream
|
||||
gt repo clone alice/project src --depth 1
|
||||
gt repo sync # fast-forward the default branch from its remote
|
||||
gt repo sync bob/project # fork without a local remote: update it on the server
|
||||
```
|
||||
| Auth | `auth`, `doctor` | [auth.md](references/auth.md) |
|
||||
| Repositories | `repo`, `branch` | [repos.md](references/repos.md) |
|
||||
| Issues | `issue`, `label`, `milestone` | [issues.md](references/issues.md) |
|
||||
| Pull requests | `pr` | [pull-requests.md](references/pull-requests.md) |
|
||||
| Releases | `release` | [releases.md](references/releases.md) |
|
||||
| Organizations | `org`, `team` | [organizations.md](references/organizations.md) |
|
||||
| Actions | `run`, `workflow` | [actions.md](references/actions.md) |
|
||||
| CI config | `secret`, `variable`, `package` | [ci-config.md](references/ci-config.md) |
|
||||
| Discovery | `search`, `status`, `notification`, `time` | [discovery.md](references/discovery.md) |
|
||||
| Instance | `config`, `api`, `alias`, `completion`, `webhook`, `wiki`, `ssh-key`, `admin` | [instance.md](references/instance.md) |
|
||||
| Recipes | end-to-end workflows | [workflows.md](references/workflows.md) |
|
||||
|
||||
## Coming from `tea`
|
||||
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
# Actions: runs and workflows
|
||||
|
||||
Gitea Actions are first-class in `gt`. This file covers `run` (workflow runs)
|
||||
and `workflow` (definitions and dispatch). Secrets, variables and packages are
|
||||
in [ci-config.md](ci-config.md). `gt <cmd> --help` is authoritative.
|
||||
|
||||
**Run argument:** a run ID (`34`, `#34`) or a run URL
|
||||
(`https://HOST/OWNER/REPO/actions/runs/34`). Without one, a terminal asks you to
|
||||
pick a recent run.
|
||||
|
||||
**JSON fields (run):** `actor, attempt, branch, commit, completed_at, conclusion,
|
||||
created_at, event, id, jobs, run_number, started_at, status, title, updated_at,
|
||||
url, workflow, workflow_path`.
|
||||
|
||||
## run
|
||||
|
||||
```text
|
||||
gt run <command>
|
||||
artifact cancel delete download jobs list logs rerun view watch
|
||||
```
|
||||
|
||||
`run list` aliases `run ls`.
|
||||
|
||||
### list
|
||||
|
||||
`-u/--actor @me`, `-b/--branch`, `-c/--commit SHA|rev`, `-e/--event`,
|
||||
`-w/--workflow file|name`, `-s/--status` (status or conclusion, repeatable),
|
||||
`--since`/`--until` (date, RFC3339, or duration ago; scans up to 5000 runs),
|
||||
`-L/--limit`, `--page`.
|
||||
|
||||
```bash
|
||||
gt run list
|
||||
gt run list --workflow CI --branch main --status failure
|
||||
gt run list --since 24h --json id,status,conclusion,workflow
|
||||
```
|
||||
|
||||
### view / watch
|
||||
|
||||
- `view [<run-id>] [--log] [--no-jobs] [-w]` — run, jobs and steps.
|
||||
- `watch [<run-id>] [-i|--interval 3s] [--timeout 1h]` — refresh until done;
|
||||
**fails when the run completes without success**; tolerates a 5-minute outage.
|
||||
|
||||
```bash
|
||||
gt run view 34
|
||||
gt run view 34 --json jobs --jq '.jobs[] | {name, conclusion}'
|
||||
gt run watch 34 --timeout 10m && echo deployed
|
||||
```
|
||||
|
||||
### logs
|
||||
|
||||
`logs [<run-id>] [-j|--job name|ID] [-f|--follow] [--failed]
|
||||
[-i|--interval 5s] [-O|--output file|-] [-D|--dir dir] [--timeout 1h]
|
||||
[--clobber] [--skip-existing]`
|
||||
|
||||
Prints each job's logs, job names to stderr. `--follow` waits for jobs to start
|
||||
and prints new lines. `--output`/`--dir` download the whole run's logs as a ZIP.
|
||||
|
||||
```bash
|
||||
gt run logs 34
|
||||
gt run logs 34 --job build --follow
|
||||
gt run logs 34 --output logs.zip
|
||||
```
|
||||
|
||||
### download
|
||||
|
||||
`download [<run-id>] [-n|--name artifact] [-D|--dir dir] [-O|--output path|-]
|
||||
[--zip] [--clobber] [--skip-existing]` — extracts each artifact into a
|
||||
directory named after it; a single `--name` extracts into the destination
|
||||
itself; `--zip` keeps archives.
|
||||
|
||||
```bash
|
||||
gt run download 34
|
||||
gt run download 34 --name build --dir dist
|
||||
gt run download 34 --zip
|
||||
```
|
||||
|
||||
### jobs / artifact list / cancel / rerun / delete
|
||||
|
||||
- `jobs [<run-id>] [-L n] [--page n]` — JSON: `completed_at, conclusion,
|
||||
created_at, id, labels, name, run_attempt, started_at, status, steps, url`.
|
||||
- `artifact list [<run-id>]` — list uploaded artifacts.
|
||||
- `cancel [<run-id>] [--force]` — keeps the run and logs.
|
||||
- `rerun [<run-id>] [--failed] [-j|--job name|ID]` — all jobs, failed only, or one.
|
||||
- `delete [<run-id>]`.
|
||||
|
||||
```bash
|
||||
gt run jobs 34 --json id,conclusion --jq '.[] | select(.conclusion == "failure") | .id'
|
||||
gt run rerun 34 --failed
|
||||
```
|
||||
|
||||
## workflow
|
||||
|
||||
```text
|
||||
gt workflow <command>
|
||||
disable enable list run view
|
||||
```
|
||||
|
||||
`workflow list` aliases `workflow ls`.
|
||||
|
||||
**Workflow argument:** file name (`ci.yml`), name without extension (`ci`),
|
||||
path (`.gitea/workflows/ci.yml`), or workflow name (`CI`).
|
||||
|
||||
**JSON fields:** `id, name, path, state, url`.
|
||||
|
||||
### run (dispatch)
|
||||
|
||||
`gt workflow run <workflow>` with `-r/--ref branch|tag`,
|
||||
`-f/--field key=value` (repeatable), `--follow`, `--interval 2s`,
|
||||
`--timeout 30m`. Requires a `workflow_dispatch` trigger. Inputs are validated
|
||||
against the declared inputs: unknown, missing-required, or invalid choice/boolean
|
||||
values are refused. The workflow must exist on the default branch (like `gh`);
|
||||
`--ref` selects the version that runs. Without `--ref`, runs on the checked-out
|
||||
branch if it is on the server, else the default branch. With `--follow`, fails
|
||||
like `gt run watch` when the run completes without success.
|
||||
|
||||
JSON fields: `id, url`.
|
||||
|
||||
```bash
|
||||
gt workflow run CI
|
||||
gt workflow run ci.yml --ref main -f target=production -f dry_run=false
|
||||
gt workflow run nightly --follow
|
||||
```
|
||||
|
||||
### view / list / enable / disable
|
||||
|
||||
- `view <workflow> [-r ref] [--yaml] [-w]` — workflow and recent runs.
|
||||
- `list`
|
||||
- `enable <workflow>`, `disable <workflow>`
|
||||
|
||||
```bash
|
||||
gt workflow view CI
|
||||
gt workflow view ci.yml --yaml --ref feature/login
|
||||
gt workflow disable Nightly
|
||||
```
|
||||
@@ -0,0 +1,92 @@
|
||||
# auth (`gt auth`)
|
||||
|
||||
Authentication, accounts, git credential setup, and environment variables.
|
||||
`gt <cmd> --help` is authoritative.
|
||||
|
||||
`gt` keeps accounts in `hosts.yml` and tokens in the system keyring (or a
|
||||
private file), under `~/.config/gitea-cli/` (`GITEA_CLI_CONFIG_DIR` overrides).
|
||||
It never reads `tea`'s config. One account per instance is active; `--user` or
|
||||
`GITEA_CLI_USER` selects another for a single command.
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
gt auth <command>
|
||||
login logout refresh setup-git status switch token
|
||||
```
|
||||
|
||||
### login
|
||||
|
||||
Without a method flag on a terminal it asks for the instance, login method,
|
||||
token storage and whether git should use `gt`.
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--with-token` | Read an access token from stdin (or prompt) |
|
||||
| `--oauth` | Authorize in a browser; `--client-id ID` selects the OAuth app |
|
||||
| `--scopes scopes` | OAuth scopes, e.g. `read:repository,read:user` (implies `--oauth`) |
|
||||
| `--credential-store {keyring\|file}` | Where to keep the token (default `keyring`) |
|
||||
| `--insecure` | Skip TLS verification for this instance |
|
||||
| `--header "Name: value"` | Send a header with every request (repeatable; `$VAR` expansion) |
|
||||
| `--ssh-key file`, `--ssh-agent-key fp`, `--ssh-agent-principal p` | Sign requests with SSH |
|
||||
| `--client-cert file`, `--client-key file` | TLS client certificate |
|
||||
| `-y, --yes` | Replace an existing account without confirming |
|
||||
|
||||
```bash
|
||||
gt auth login
|
||||
gt auth login --host gitea.com --with-token < token.txt
|
||||
gt auth login --host gitea.com --oauth --scopes read:repository,read:user
|
||||
gt auth login --host g.example.com --with-token \
|
||||
--header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET'
|
||||
```
|
||||
|
||||
Create a token on the instance under **Settings > Applications**. The first
|
||||
instance logged in to becomes `default_host` unless one is set.
|
||||
|
||||
### status / token / switch / setup-git / logout / refresh
|
||||
|
||||
- `status [--verify] [--json ...]` — accounts per instance, active one, method.
|
||||
Fails with exit **4** when there is no account or the credential is
|
||||
missing/rejected; with `--json` it exits 0 and you read
|
||||
`credential_available`, `verified`, `error`. JSON fields: `active,
|
||||
credential_available, credential_store, error, expires_at,
|
||||
git_credential_helper, host, method, scopes, user, verified`.
|
||||
- `token` — print the active token (refreshing an expiring OAuth token). SSH-key
|
||||
accounts have no token.
|
||||
- `switch` — change the active account of an instance.
|
||||
- `setup-git [--keep-helpers] [--local]` — configure git to ask `gt` for
|
||||
credentials. Other credential helpers are turned off for the instance unless
|
||||
`--keep-helpers`; `--local` configures only the current repository.
|
||||
- `logout` — log out of an account.
|
||||
- `refresh` — refresh an OAuth token.
|
||||
|
||||
```bash
|
||||
gt auth status --verify
|
||||
gt auth status --host gitea.com --json
|
||||
curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
- `GITEA_TOKEN` + `GITEA_INSTANCE_URL` (or `GITEA_CLI_HOST`): use a token
|
||||
instead of stored credentials. `GITEA_TOKEN` replaces the active account of
|
||||
its instance for the active account too; it must belong to the account
|
||||
`--user`/`GITEA_CLI_USER` names.
|
||||
- `GITEA_CLI_*` prefixed variables mirror global flags and settings; see
|
||||
`gt help environment` for the full list (config dir, user, repo, editor,
|
||||
pager, color, http timeout, ...).
|
||||
- `GITEA_INSTANCE_INSECURE`, `GITEA_INSTANCE_SSH_HOST`: pair with `GITEA_TOKEN`.
|
||||
|
||||
## doctor
|
||||
|
||||
`gt doctor [-R ...] [--json ...]` checks the setup commands in this directory
|
||||
use: settings files, the instance and its headers, whether it answers, the
|
||||
account and credential, the repository, and git. Each problem names the command
|
||||
that fixes it; `gt doctor` fails when a check fails. JSON fields: `checks,
|
||||
host, host_source, repo, repo_source, user, user_source`.
|
||||
|
||||
```bash
|
||||
gt doctor
|
||||
gt doctor -R gitea.com/gitea/cli
|
||||
gt doctor --jq '.checks[] | select(.status == "failed")'
|
||||
```
|
||||
@@ -0,0 +1,97 @@
|
||||
# CI configuration: secrets, variables, packages
|
||||
|
||||
Actions secrets and variables and the package registry. Workflow files and
|
||||
dispatch are in [actions.md](actions.md). `gt <cmd> --help` is authoritative.
|
||||
|
||||
**Scoping (secrets and variables):** repository (default), organization
|
||||
(`--org`), or your account (`--account`). Names are stored **upper-cased**.
|
||||
|
||||
> The global `--user` flag selects the account `gt` acts as — it is **not** a
|
||||
> scope. Use `--org` / `--account` for scope.
|
||||
|
||||
## secret
|
||||
|
||||
```text
|
||||
gt secret <command>
|
||||
delete list set
|
||||
```
|
||||
|
||||
Read by workflows as `${{ secrets.NAME }}`. Secret values are never shown.
|
||||
|
||||
- `set [<name>] [-b|--body value] [-F|--body-file file|-] [-d|--description]
|
||||
[-f|--env-file file|-] [-o|--org ORG] [--account]` — `--env-file` sets every
|
||||
`NAME=value` of a dotenv file. The value comes from the flag/file, else stdin
|
||||
when not a terminal (one trailing newline removed), else a prompt. Setting an
|
||||
existing secret without `--description` clears its description.
|
||||
- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`)
|
||||
- `delete <name> [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`)
|
||||
|
||||
JSON: `created_at, description, name`.
|
||||
|
||||
```bash
|
||||
gt secret set DEPLOY_TOKEN
|
||||
echo -n "$TOKEN" | gt secret set NPM_TOKEN --org acme
|
||||
gt secret set --env-file .env
|
||||
gt secret list --org acme
|
||||
```
|
||||
|
||||
## variable
|
||||
|
||||
```text
|
||||
gt variable <command>
|
||||
delete get list set view
|
||||
```
|
||||
|
||||
Read by workflows as `${{ vars.NAME }}`. Same scoping and naming rules as
|
||||
secrets.
|
||||
|
||||
**JSON fields:** `description, name, value`.
|
||||
|
||||
- `set [<name>] [-b value] [-F file|-] [-d description] [-f|--env-file file|-]
|
||||
[-o|--org ORG] [--account]`
|
||||
- `get <name> [...]` — print just the value (for scripts).
|
||||
- `view <name>` — value plus description.
|
||||
- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`)
|
||||
- `delete <name> [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`)
|
||||
|
||||
```bash
|
||||
gt variable set ENVIRONMENT --body staging
|
||||
gt variable set CONFIG --org acme < config.json
|
||||
gt variable set --env-file .env
|
||||
region=$(gt variable get REGION --org acme)
|
||||
gt variable list --org acme
|
||||
```
|
||||
|
||||
## package
|
||||
|
||||
```text
|
||||
gt package <command>
|
||||
delete link list unlink upload versions view
|
||||
```
|
||||
|
||||
Packages live in the registry of a user or organization: the owner of the
|
||||
selected repository, else your account, unless `--owner` names another. A
|
||||
package is addressed by **type** (e.g. `generic`, `npm`, `container`) and
|
||||
**name**.
|
||||
|
||||
`package list` aliases `package ls`; `package delete` aliases `package rm`.
|
||||
|
||||
**JSON fields:** `created_at, creator, id, name, owner, repository, type, url,
|
||||
version`; `view` adds `files`.
|
||||
|
||||
- `list [-t|--type type] [-S|--search text] [--owner OWNER] [-L n] [--page n]`
|
||||
- `versions <type> <name> [--owner] [-L n] [--page n]`
|
||||
- `view <type> <name> [<version>] [--owner]` — latest version without one.
|
||||
- `upload <name> <version> <file>... [--owner]` — generic packages; each file
|
||||
is stored under its base name; a version cannot hold two files of the same
|
||||
name.
|
||||
- `link <type> <name> <repository> [--owner]`
|
||||
- `unlink <type> <name> [--owner]`
|
||||
- `delete <type> <name> [<version>] [--all] [--owner] [-y|--yes]`
|
||||
|
||||
```bash
|
||||
gt package upload tool 1.0.0 dist/tool-linux-amd64 dist/tool-darwin-arm64
|
||||
gt package list --owner acme --type container
|
||||
gt package versions generic tool
|
||||
gt package delete generic tool 1.0.0
|
||||
```
|
||||
@@ -1,262 +0,0 @@
|
||||
# Command reference: Actions
|
||||
|
||||
`gt` treats Gitea Actions as first-class. Groups: `run` (workflow runs), `workflow`
|
||||
(definitions and dispatch), `secret`, `variable`, `package` (registry), and `admin`.
|
||||
|
||||
`gt <group> <cmd> --help` is authoritative for the installed version.
|
||||
|
||||
**Run argument:** a run ID (`34`, `#34`) or a run URL
|
||||
(`https://HOST/OWNER/REPO/actions/runs/34`). Without one, a terminal asks you to
|
||||
pick a recent run.
|
||||
|
||||
**JSON fields (run):** `actor, attempt, branch, commit, completed_at, conclusion,
|
||||
created_at, event, id, jobs, run_number, started_at, status, title, updated_at,
|
||||
url, workflow, workflow_path`.
|
||||
|
||||
---
|
||||
|
||||
## run
|
||||
|
||||
```text
|
||||
gt run <command>
|
||||
artifact cancel delete download jobs list logs rerun view watch
|
||||
```
|
||||
|
||||
`run list` aliases `run ls`.
|
||||
|
||||
### list
|
||||
|
||||
`-u/--actor @me`, `-b/--branch`, `-c/--commit SHA|rev`, `-e/--event`,
|
||||
`-w/--workflow file|name`, `-s/--status` (status or conclusion, repeatable),
|
||||
`--since`/`--until` (date, RFC3339, or duration ago; scans up to 5000 runs),
|
||||
`-L/--limit`, `--page`.
|
||||
|
||||
```bash
|
||||
gt run list
|
||||
gt run list --workflow CI --branch main --status failure
|
||||
gt run list --since 24h --json id,status,conclusion,workflow
|
||||
```
|
||||
|
||||
### view / watch
|
||||
|
||||
- `view [<run-id>] [--log] [--no-jobs] [-w]` — run, jobs and steps.
|
||||
- `watch [<run-id>] [-i|--interval 3s] [--timeout 1h]` — refresh until done;
|
||||
**fails when the run completes without success**; tolerates a 5-minute outage.
|
||||
|
||||
```bash
|
||||
gt run view 34
|
||||
gt run view 34 --json jobs --jq '.jobs[] | {name, conclusion}'
|
||||
gt run watch 34 --timeout 10m && echo deployed
|
||||
```
|
||||
|
||||
### logs
|
||||
|
||||
`logs [<run-id>] [-j|--job name|ID] [-f|--follow] [--failed]
|
||||
[-i|--interval 5s] [-O|--output file|-] [-D|--dir dir] [--timeout 1h]
|
||||
[--clobber] [--skip-existing]`
|
||||
|
||||
Prints each job's logs, job names to stderr. `--follow` waits for jobs and new
|
||||
lines. `--output`/`--dir` download the whole run's logs as a ZIP.
|
||||
|
||||
```bash
|
||||
gt run logs 34
|
||||
gt run logs 34 --job build --follow
|
||||
gt run logs 34 --output logs.zip
|
||||
```
|
||||
|
||||
### download
|
||||
|
||||
`download [<run-id>] [-n|--name artifact] [-D|--dir dir] [-O|--output path|-]
|
||||
[--zip] [--clobber] [--skip-existing]` — extracts each artifact into a
|
||||
directory named after it; a single `--name` extracts into the destination
|
||||
itself; `--zip` keeps archives.
|
||||
|
||||
```bash
|
||||
gt run download 34
|
||||
gt run download 34 --name build --dir dist
|
||||
gt run download 34 --zip
|
||||
```
|
||||
|
||||
### jobs / artifact list / cancel / rerun / delete
|
||||
|
||||
- `jobs [<run-id>] [-L n] [--page n]` — JSON: `completed_at, conclusion,
|
||||
created_at, id, labels, name, run_attempt, started_at, status, steps, url`.
|
||||
- `artifact list [<run-id>]` — list uploaded artifacts.
|
||||
- `cancel [<run-id>] [--force]` — keeps the run and logs.
|
||||
- `rerun [<run-id>] [--failed] [-j|--job name|ID]` — all jobs, failed only, or one.
|
||||
- `delete [<run-id>]`.
|
||||
|
||||
```bash
|
||||
gt run jobs 34 --json id,conclusion --jq '.[] | select(.conclusion == "failure") | .id'
|
||||
gt run rerun 34 --failed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## workflow
|
||||
|
||||
```text
|
||||
gt workflow <command>
|
||||
disable enable list run view
|
||||
```
|
||||
|
||||
`workflow list` aliases `workflow ls`.
|
||||
|
||||
**Workflow argument:** file name (`ci.yml`), name without extension (`ci`),
|
||||
path (`.gitea/workflows/ci.yml`), or workflow name (`CI`).
|
||||
|
||||
**JSON fields:** `id, name, path, state, url`.
|
||||
|
||||
### run (dispatch)
|
||||
|
||||
`gt workflow run <workflow>` with `-r/--ref branch|tag`,
|
||||
`-f/--field key=value` (repeatable), `--follow`, `--interval 2s`,
|
||||
`--timeout 30m`. Requires a `workflow_dispatch` trigger. Inputs are validated
|
||||
against the declared inputs: unknown, missing-required, or invalid choice/boolean
|
||||
values are refused. The workflow must exist on the default branch (like `gh`);
|
||||
`--ref` selects the version that runs. Without `--ref`, runs on the checked-out
|
||||
branch if it is on the server.
|
||||
|
||||
JSON fields: `id, url`.
|
||||
|
||||
```bash
|
||||
gt workflow run CI
|
||||
gt workflow run ci.yml --ref main -f target=production -f dry_run=false
|
||||
gt workflow run nightly --follow
|
||||
```
|
||||
|
||||
### view / list / enable / disable
|
||||
|
||||
- `view <workflow> [-r ref] [--yaml] [-w]` — workflow and recent runs.
|
||||
- `list`
|
||||
- `enable <workflow>`, `disable <workflow>`
|
||||
|
||||
```bash
|
||||
gt workflow view CI
|
||||
gt workflow view ci.yml --yaml --ref feature/login
|
||||
gt workflow disable Nightly
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## secret
|
||||
|
||||
```text
|
||||
gt secret <command>
|
||||
delete list set
|
||||
```
|
||||
|
||||
Secrets are read by workflows as `${{ secrets.NAME }}`. Scope: repository
|
||||
(default), organization (`--org`), or your account (`--account`). Names are
|
||||
stored **upper-cased**.
|
||||
|
||||
> The global `--user` flag selects the account `gt` acts as — it is **not** a
|
||||
> scope. Use `--org` / `--account` for scope.
|
||||
|
||||
### set
|
||||
|
||||
`gt secret set [<name>]` with `-b/--body value`, `-F/--body-file file|-`,
|
||||
`-d/--description`, `-f/--env-file file|-` (sets every `NAME=value`).
|
||||
The value comes from the flag/file, else stdin when not a terminal (one
|
||||
trailing line break removed), else a prompt.
|
||||
|
||||
JSON: `created_at, description, name`.
|
||||
|
||||
```bash
|
||||
gt secret set DEPLOY_TOKEN
|
||||
echo -n "$TOKEN" | gt secret set NPM_TOKEN --org acme
|
||||
gt secret set --env-file .env
|
||||
```
|
||||
|
||||
### list / delete
|
||||
|
||||
- `list [-L n] [--page n] [-o|--org ORG]` (alias `ls`)
|
||||
- `delete <name> [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`)
|
||||
|
||||
```bash
|
||||
gt secret list --org acme
|
||||
gt secret delete DEPLOY_TOKEN --org acme --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## variable
|
||||
|
||||
```text
|
||||
gt variable <command>
|
||||
delete get list set view
|
||||
```
|
||||
|
||||
Variables are read by workflows as `${{ vars.NAME }}`. Same scoping and naming
|
||||
rules as secrets (`--org`, `--account`; names upper-cased).
|
||||
|
||||
**JSON fields:** `description, name, value`.
|
||||
|
||||
### set / get / view / list / delete
|
||||
|
||||
- `set [<name>] [-b value] [-F file|-] [-d description] [-f|--env-file file|-]
|
||||
[-o|--org ORG] [--account]`
|
||||
- `get <name> [...]` — print just the value (for scripts).
|
||||
- `view <name>` — value plus description.
|
||||
- `list [-L n] [--page n] [-o|--org ORG] [--account]` (alias `ls`)
|
||||
- `delete <name> [-o|--org ORG] [--account] [-y|--yes]` (alias `rm`)
|
||||
|
||||
```bash
|
||||
gt variable set ENVIRONMENT --body staging
|
||||
gt variable set CONFIG --org acme < config.json
|
||||
gt variable set --env-file .env
|
||||
region=$(gt variable get REGION --org acme)
|
||||
gt variable list --org acme
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## package
|
||||
|
||||
```text
|
||||
gt package <command>
|
||||
delete link list unlink upload versions view
|
||||
```
|
||||
|
||||
Packages live in the registry of a user or organization: the owner of the
|
||||
selected repository, else your account, unless `--owner` names another. A
|
||||
package is addressed by **type** (e.g. `generic`, `npm`, `container`) and
|
||||
**name**.
|
||||
|
||||
`package list` aliases `package ls`; `package delete` aliases `package rm`.
|
||||
|
||||
**JSON fields:** `created_at, creator, id, name, owner, repository, type, url,
|
||||
version`; `view` adds `files`.
|
||||
|
||||
- `list [-t|--type type] [-S|--search text] [--owner OWNER] [-L n] [--page n]`
|
||||
- `versions <type> <name> [--owner] [-L n] [--page n]`
|
||||
- `view <type> <name> [<version>] [--owner]` — latest version without one.
|
||||
- `upload <name> <version> <file>... [--owner]` — generic packages; each file
|
||||
is stored under its base name.
|
||||
- `link <type> <name> <repository> [--owner]`
|
||||
- `unlink <type> <name> [--owner]`
|
||||
- `delete <type> <name> [<version>] [--all] [--owner] [-y|--yes]`
|
||||
|
||||
```bash
|
||||
gt package upload tool 1.0.0 dist/tool-linux-amd64 dist/tool-darwin-arm64
|
||||
gt package list --owner acme --type container
|
||||
gt package versions generic tool
|
||||
gt package delete generic tool 1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## admin
|
||||
|
||||
```text
|
||||
gt admin <command>
|
||||
user (list, view, create, edit, delete)
|
||||
```
|
||||
|
||||
Instance administration; requires an administrator account. (`--sudo user` on
|
||||
other commands acts as another user.)
|
||||
|
||||
```bash
|
||||
gt admin user list
|
||||
gt admin user create alice --email alice@example.com
|
||||
```
|
||||
@@ -1,428 +0,0 @@
|
||||
# Command reference: core
|
||||
|
||||
Per-command flags, arguments, JSON fields and examples for the core `gt` groups:
|
||||
`auth`, `repo`, `issue`, `pr`, `release`, `org`, `label`, `milestone`, `branch`.
|
||||
|
||||
`gt <group> <cmd> --help` is authoritative for the installed version.
|
||||
|
||||
## Shared flags
|
||||
|
||||
- **Repository-scoped groups** (`repo`, `issue`, `pr`, `release`, `branch`,
|
||||
`label`, `milestone`) inherit:
|
||||
`-R, --repo OWNER/REPO`, `--remote remote`, `--cwd directory`.
|
||||
- **List/view commands** additionally inherit `--json fields` and
|
||||
`-q, --jq expression` (see `gt help formatting`).
|
||||
- **Mutating commands** that confirm inherit `-y, --yes`.
|
||||
- Global flags (`--host`, `--user`, `--sudo`, `--no-input`, `--interactive`,
|
||||
`--debug`) work everywhere; see `gt help environment`.
|
||||
|
||||
---
|
||||
|
||||
## auth
|
||||
|
||||
```text
|
||||
gt auth <command>
|
||||
login logout refresh setup-git status switch token
|
||||
```
|
||||
|
||||
### gt auth login
|
||||
|
||||
Log in to a Gitea instance. Without a method flag on a terminal it asks for the
|
||||
instance, login method, token storage and whether git should use `gt`.
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `--with-token` | Read an access token from stdin (or prompt) |
|
||||
| `--oauth` | Authorize in a browser; `--client-id ID` selects the OAuth app |
|
||||
| `--scopes scopes` | OAuth scopes, e.g. `read:repository,read:user` (implies `--oauth`) |
|
||||
| `--credential-store {keyring\|file}` | Where to keep the token (default `keyring`) |
|
||||
| `--insecure` | Skip TLS verification for this instance |
|
||||
| `--header "Name: value"` | Send a header with every request (repeatable; `$VAR` expansion) |
|
||||
| `--ssh-key file`, `--ssh-agent-key fp`, `--ssh-agent-principal p` | Sign requests with SSH |
|
||||
| `--client-cert file`, `--client-key file` | TLS client certificate |
|
||||
| `-y, --yes` | Replace an existing account without confirming |
|
||||
|
||||
```bash
|
||||
gt auth login
|
||||
gt auth login --host gitea.com --with-token < token.txt
|
||||
gt auth login --host gitea.com --oauth --scopes read:repository,read:user
|
||||
gt auth login --host g.example.com --with-token \
|
||||
--header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET'
|
||||
```
|
||||
|
||||
### gt auth status / token / switch / setup-git / logout / refresh
|
||||
|
||||
- `status [--verify] [--json ...]` — accounts per instance, active one, method.
|
||||
Fails exit 4 when there is no account or the credential is missing/rejected;
|
||||
with `--json` it exits 0 and you read `credential_available`, `verified`,
|
||||
`error`. JSON fields: `active, credential_available, credential_store, error,
|
||||
expires_at, git_credential_helper, host, method, scopes, user, verified`.
|
||||
- `token` — print the active token (refreshing an expiring OAuth token). SSH-key
|
||||
accounts have no token.
|
||||
- `switch` — change the active account of an instance.
|
||||
- `setup-git [--keep-helpers] [--local]` — configure git to ask `gt` for
|
||||
credentials.
|
||||
- `logout`, `refresh` (refresh an OAuth token).
|
||||
|
||||
```bash
|
||||
gt auth status --verify
|
||||
curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## repo
|
||||
|
||||
```text
|
||||
gt repo <command>
|
||||
archive clone create delete deploy-key edit fork list migrate
|
||||
rename set-default sync transfer unarchive view
|
||||
```
|
||||
|
||||
`repo list` aliases `repo ls`; `repo create` aliases `repo new`.
|
||||
|
||||
**Repository argument** (where accepted): `NAME` (one of yours), `OWNER/NAME`,
|
||||
`HOST/OWNER/NAME`, or a URL. Without one, the current clone's repository.
|
||||
|
||||
**JSON fields (repo objects):** `actions_enabled, archived, clone_url,
|
||||
default_branch, description, empty, fork, forks_count, full_name, id, mirror,
|
||||
mirror_interval, name, open_issues_count, open_pr_count, original_url, parent,
|
||||
private, ssh_url, stars_count, template, topics, updated_at, url, website`.
|
||||
|
||||
### Key subcommands
|
||||
|
||||
- `list [<owner>] [--starred] [--watched] [--type {fork|source|mirror}] [-L n]
|
||||
[--page n]`
|
||||
- `view [<repo>] [-b branch] [-w]`
|
||||
- `create [<name>] [--org ORG] [--private|--public] [--auto-init]
|
||||
[--readme TMPL] [--gitignores TMPL] [--license TMPL] [--default-branch NAME]
|
||||
[-d DESC] [--template OWNER/REPO] [--source DIR] [--push] [--clone]
|
||||
[--as-template]`
|
||||
- `clone <repo> [<dir>] [-- <gitflags>] [-d depth] [--no-upstream]
|
||||
[-u upstream-name]` — a fork's parent is added as `upstream`; a mirror's
|
||||
source as `source`.
|
||||
- `fork [<repo>] [--clone] [--org ORG] [--remote] [--remote-name NAME]
|
||||
[--fork-name NAME] [-- <gitflags>]` — inside a clone, `--remote` adds the fork
|
||||
as `origin` and renames the old `origin` to `upstream`.
|
||||
- `sync [<repo>] [-b branch]` — fast-forward a local branch (default: default
|
||||
branch) from its remote without switching; for a fork/mirror without a local
|
||||
remote, updates it on the server. JSON: `branch, commit, previous, remote`.
|
||||
- `set-default [<repo>] [-u|--unset] [-v|--view]` — store `gt.repository` in the
|
||||
clone so commands target it instead of the git remotes.
|
||||
- `edit`, `delete`, `rename`, `transfer`, `archive`, `unarchive`, `migrate`,
|
||||
`deploy-key`.
|
||||
|
||||
```bash
|
||||
gt repo list --starred --json full_name,url
|
||||
gt repo create project --private --auto-init --license MIT
|
||||
gt repo create acme/service --template acme/service-template
|
||||
gt repo create project --source . --push
|
||||
gt repo fork alice/project --clone -- --depth 1
|
||||
gt repo sync --branch release/1.0
|
||||
gt repo sync bob/project # update the fork on the server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## issue
|
||||
|
||||
```text
|
||||
gt issue <command>
|
||||
attachment close comment create edit list reopen timeline view
|
||||
```
|
||||
|
||||
`issue list` aliases `issue ls`; `issue create` aliases `issue new`.
|
||||
|
||||
**Issue argument:** `123`, `#123`, a URL, or `OWNER/REPO#123`.
|
||||
|
||||
**JSON fields (issue):** `assignees, author, body, comments, created_at,
|
||||
due_date, id, kind, labels, milestone, number, ref, state, title, updated_at,
|
||||
url`. `view`/`edit` add `blocked_by, blocks` (extra requests, only when named).
|
||||
|
||||
### list
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-s, --state {open\|closed\|all}` | default `open` |
|
||||
| `-a, --assignee`, `-A, --author`, `--mentions` | `@me` for yourself |
|
||||
| `--no-assignee` | only issues without an assignee |
|
||||
| `-l, --label names`, `-m, --milestone titles` | filters |
|
||||
| `--kind {issues\|pulls\|all}` | include PRs (Gitea lists PRs among issues) |
|
||||
| `-S, --search text` | search titles and bodies |
|
||||
| `--since`, `--until` | updated window (date, timestamp, or duration ago) |
|
||||
| `-L, --limit n` (1..1000, default 30), `--page n` | pagination |
|
||||
| `-w, --web` | open in browser |
|
||||
|
||||
```bash
|
||||
gt issue list --label bug --state all
|
||||
gt issue list --assignee @me --json number,title
|
||||
gt issue list --kind all --milestone v1.0 | cut -f1,2
|
||||
```
|
||||
|
||||
### create
|
||||
|
||||
`-t/--title`, `-b/--body`, `-F/--body-file file|-`, `-e/--editor`,
|
||||
`-a/--assignee login`, `-l/--label name` (prefix `repo:`/`org:` to disambiguate),
|
||||
`-m/--milestone`, `-p/--project`, `--ref`, `--deadline DATE`,
|
||||
`-T/--template name`, `--attachment File`, `-w/--web`.
|
||||
|
||||
Gitea applies labels/milestone/assignees/deadline only to users with issue write
|
||||
access; otherwise `gt` reports the left-out fields and fails.
|
||||
|
||||
```bash
|
||||
gt issue create --title "Crash on start" --body "Steps..." \
|
||||
--label bug --milestone v1.0
|
||||
gt issue create --template "Bug report"
|
||||
```
|
||||
|
||||
### edit
|
||||
|
||||
Adds/removes relative to current values, or replaces with `--set-*`:
|
||||
`--add-label`, `--remove-label`, `--set-labels`, `--add-assignee`,
|
||||
`--remove-assignee`, `--set-assignees`, `-m/--milestone`,
|
||||
`--remove-milestone`, `--add-blocked-by`, `--remove-blocked-by`,
|
||||
`--add-project`, `--remove-project`, `-t/--title`, `-b/--body`,
|
||||
`-F/--body-file`, `-e/--editor`, `--ref`, `--deadline`. Accepts multiple issues.
|
||||
|
||||
```bash
|
||||
gt issue edit 12 --title "Crash on start" --add-label bug
|
||||
gt issue edit 12 13 --add-assignee @me --milestone v1.0
|
||||
gt issue edit 12 --add-blocked-by 9
|
||||
```
|
||||
|
||||
### close / reopen / comment / timeline / view / attachment
|
||||
|
||||
- `close {N}... [-c comment]`, `reopen {N}...`
|
||||
- `comment {N} [-b text] [-F file] [-e] [--edit-last] [--delete-last]
|
||||
[--attachment File]`; subcommands `list|view|edit|delete`. JSON: `author,
|
||||
body, created_at, id, issue_number, updated_at, url`.
|
||||
- `timeline {N} [-L n] [--page n]` — comments and changes, oldest first.
|
||||
- `view {N} [-c|--comments] [-w]`
|
||||
- `attachment {list|view|upload|download|edit|delete}`
|
||||
|
||||
```bash
|
||||
gt issue view 12 --comments
|
||||
gt issue comment 12 --body "Fixed in #14"
|
||||
gt issue close 12 13 --comment "Done in #14"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## pr
|
||||
|
||||
```text
|
||||
gt pr <command>
|
||||
attachment checkout checks clean close comment create diff
|
||||
edit list merge ready reopen review status timeline view
|
||||
```
|
||||
|
||||
`pr list` aliases `pr ls`; `pr create` aliases `pr new`; `pr checkout` aliases
|
||||
`pr co`.
|
||||
|
||||
**PR argument:** `13`, `#13`, a URL, or a head branch name (e.g. `feature/login`
|
||||
or `bob:feature/login`). Without one, the PR of the current branch.
|
||||
|
||||
**JSON fields (PR):** `assignees, author, base, body, comments, created_at,
|
||||
draft, due_date, head, head_remote_deleted, head_repo, head_sha, id, labels,
|
||||
merge_commit_sha, mergeable, merged, merged_at, merged_by, milestone, number,
|
||||
review_decision, reviewer_teams, reviewers, reviews, state, title, updated_at,
|
||||
url`. `reviewers`, `reviewer_teams`, `reviews`, `review_decision` and
|
||||
`merged_by` on `list` cost extra requests and are fetched only when named.
|
||||
|
||||
### list
|
||||
|
||||
`-s, --state {open|closed|merged|all}` (default `open`), `-a/--assignee`,
|
||||
`-A/--author`, `--no-assignee`, `-l/--label`, `-m/--milestone`,
|
||||
`-B/--base branch`, `-H/--head branch|OWNER:BRANCH`, `-d/--draft`,
|
||||
`-S/--search`, `--sort`, `-L/--limit`, `--page`, `-w/--web`.
|
||||
|
||||
### create
|
||||
|
||||
`--fill` (title/body from commits), `-t/--title`, `-b/--body`,
|
||||
`-F/--body-file`, `-e/--editor`, `-B/--base`, `-H/--head`, `-d/--draft`,
|
||||
`-a/--assignee`, `-r/--reviewer`, `--reviewer-team`, `-l/--label`,
|
||||
`-m/--milestone`, `-p/--project`, `--deadline`, `--attachment`,
|
||||
`--allow-maintainer-edits` (default true), `--agit` (+ `--topic`), `-w/--web`,
|
||||
`-y/--yes`.
|
||||
|
||||
Pushes a not-yet-remote branch after confirmation (`--yes` in CI). A branch
|
||||
without a same-named upstream goes to the fork when origin is a fork, or to the
|
||||
only remote of your own fork; otherwise to the repository's remote.
|
||||
|
||||
```bash
|
||||
gt pr create --fill --yes
|
||||
gt pr create -t "Add login" -b "Closes #1" -B develop -r carol -l enhancement
|
||||
```
|
||||
|
||||
### checkout / diff / checks
|
||||
|
||||
- `checkout {N|url|branch} [-b branch] [--detach] [--update]` — local branch
|
||||
tracking the head. JSON: `branch, commit, detached, remote, tracking`.
|
||||
- `diff [{N|url|branch}] [--name-only] [--color auto|always|never] [-w]` — clean
|
||||
diff when piped (`gt pr diff 13 | git apply`).
|
||||
- `checks [{N|url|branch}] [--watch] [--interval d] [--timeout d] [-w]` — exit
|
||||
**8** while pending, **1** on failure. JSON: `created_at, description, id,
|
||||
name, sha, state, updated_at, url`.
|
||||
|
||||
```bash
|
||||
gt pr checkout 13 --update
|
||||
gt pr diff 13 | git apply
|
||||
gt pr checks 13 --watch && gt pr merge 13
|
||||
```
|
||||
|
||||
### merge
|
||||
|
||||
`-s/--method {merge|rebase|rebase-merge|squash|fast-forward-only}` (default:
|
||||
repo's style), shortcuts `--merge`, `--rebase`, `--squash`, `--auto`
|
||||
(after checks), `-d/--delete-branch` (also deletes the local head branch when
|
||||
checked out), `-t/--title`, `-b/--message`, `-F/--message-file`, `-e/--editor`.
|
||||
|
||||
```bash
|
||||
gt pr merge 13 --squash --delete-branch
|
||||
gt pr merge 13 --auto --yes
|
||||
```
|
||||
|
||||
### review
|
||||
|
||||
Choose the type with `-a/--approve`, `-r/--request-changes` (needs a body), or
|
||||
`-c/--comment`. Flags: `-b/--body`, `-F/--body-file`, `-e/--editor`,
|
||||
`--pending` (save for later), `--commit sha`,
|
||||
`--comments-file file` (JSON array of `path`, `body`, `new_position` or
|
||||
`old_position`), `-y/--yes`. Subcommands: `create, list, view, delete, submit,
|
||||
request, cancel-request, comments, reply, resolve, unresolve, dismiss,
|
||||
undismiss`. JSON: `author, body, comments_count, commit, dismissed, id,
|
||||
official, stale, state, submitted_at, team, url`.
|
||||
|
||||
On a terminal, no type opens an interactive review that can annotate the diff
|
||||
in your editor.
|
||||
|
||||
```bash
|
||||
gt pr review --approve
|
||||
gt pr review 13 -r -b "Please hash the password"
|
||||
gt pr review 13 --pending --comments-file inline.json
|
||||
gt pr review submit 13 --approve
|
||||
```
|
||||
|
||||
### status / clean / ready / comment
|
||||
|
||||
- `status [--limit n]` — current branch's PR with checks/review, then your
|
||||
authored/assigned/review-requested PRs. JSON: `assigned, authored,
|
||||
current_branch, review_requested`.
|
||||
- `clean [{...}] [--ignore-sha]` — delete the branch of a merged/closed PR
|
||||
locally and on Gitea. JSON: `default_branch, local_branch, remote,
|
||||
remote_branch, remote_deleted, remote_skip_reason, remote_skipped`.
|
||||
- `ready [{...}] [--undo]` — mark ready/back to draft (toggles `WIP:`/`[WIP]`).
|
||||
- `comment` — like `issue comment` (JSON: `author, body, created_at, id,
|
||||
issue_number, updated_at, url`).
|
||||
- `view`, `edit`, `close`, `reopen`, `timeline`, `attachment`.
|
||||
|
||||
---
|
||||
|
||||
## release
|
||||
|
||||
```text
|
||||
gt release <command>
|
||||
asset create delete download edit list publish upload view
|
||||
```
|
||||
|
||||
`release list` aliases `release ls`; `release create` aliases `release new`.
|
||||
|
||||
**JSON fields:** `assets, author, body, created_at, draft, id, prerelease,
|
||||
published_at, tag, target, title, url`.
|
||||
|
||||
### create
|
||||
|
||||
`gt release create [<tag>] [<file>...]` with `-t/--title`, `-n/--notes`,
|
||||
`-F/--notes-file`, `-e/--editor`, `-d/--draft`, `-p/--prerelease`,
|
||||
`--target branch|commit` (for a new tag), `--asset File`, `--verify-tag`.
|
||||
|
||||
`gt` **never pushes**: push the tag first, or let Gitea create it with
|
||||
`--target`. A tag that exists only in your clone is refused without `--target`.
|
||||
|
||||
```bash
|
||||
gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md
|
||||
gt release create v1.1.0-rc1 --target release/1.1 --draft --prerelease --title "1.1 RC 1"
|
||||
```
|
||||
|
||||
### upload / download / asset / publish / edit / delete / list / view
|
||||
|
||||
- `upload <tag> <file>... [--name NAME] [--clobber]` — JSON per asset:
|
||||
`created_at, download_count, id, name, size, url`.
|
||||
- `download <tag> [...]`, `asset <list|...>`, `publish <tag>...`,
|
||||
`edit <tag>...`, `delete <tag>...`, `list [-L n] [--page n]`,
|
||||
`view <tag>`.
|
||||
|
||||
```bash
|
||||
gt release upload v1.0.0 dist/tool-linux --clobber
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## org
|
||||
|
||||
```text
|
||||
gt org <command>
|
||||
create delete edit list member view
|
||||
```
|
||||
|
||||
Organizations you belong to. Teams are in `team` (see
|
||||
`commands-misc.md`).
|
||||
|
||||
```bash
|
||||
gt org list
|
||||
gt org view acme
|
||||
gt org member list acme
|
||||
gt org create acme --description "Acme org"
|
||||
```
|
||||
|
||||
## label
|
||||
|
||||
```text
|
||||
gt label <command>
|
||||
create delete edit export import list
|
||||
```
|
||||
|
||||
Scope with `--org organization` for organization labels; otherwise the
|
||||
repository's. Addressed by name or ID. JSON: `color, description, exclusive,
|
||||
id, is_archived, name`.
|
||||
|
||||
`create <name> [-c color] [-d description] [--exclusive] [--archived]
|
||||
[-f/--force]` — random color without `-c`; `--force` updates on name clash.
|
||||
|
||||
```bash
|
||||
gt label create bug --color d73a4a --description "Something is broken"
|
||||
gt label create "priority/high" --exclusive
|
||||
gt label export labels.yml
|
||||
gt label import labels.yml
|
||||
```
|
||||
|
||||
## milestone
|
||||
|
||||
```text
|
||||
gt milestone <command>
|
||||
close create delete edit issue list reopen view
|
||||
```
|
||||
|
||||
Addressed by title or ID. `milestone issue` manages the issues/PRs in it.
|
||||
|
||||
```bash
|
||||
gt milestone create v1.0 --deadline 2026-12-31 --description "First release"
|
||||
gt milestone list --state open
|
||||
gt milestone issue list v1.0
|
||||
```
|
||||
|
||||
## branch
|
||||
|
||||
```text
|
||||
gt branch <command>
|
||||
create delete list protect rename unprotect view
|
||||
```
|
||||
|
||||
Server-side branches (use `git` for local branches).
|
||||
|
||||
```bash
|
||||
gt branch list
|
||||
gt branch create release/1.0 --source main
|
||||
gt branch protect main --required-approvals 2 --status-check ci/build
|
||||
gt branch view main
|
||||
```
|
||||
@@ -1,331 +0,0 @@
|
||||
# Command reference: misc
|
||||
|
||||
Remaining `gt` groups: `team`, `notification`, `search`, `status`, `time`,
|
||||
`webhook`, `wiki`, `ssh-key`, `api`, `config`, `alias`, `completion`.
|
||||
|
||||
`gt <group> <cmd> --help` is authoritative for the installed version.
|
||||
|
||||
---
|
||||
|
||||
## team
|
||||
|
||||
```text
|
||||
gt team <command>
|
||||
create delete edit list member repo view
|
||||
```
|
||||
|
||||
Teams grant members access to an organization's repositories. In JSON, `access`
|
||||
is the effective access shown in text (e.g. `write`, `"write (code, issues,
|
||||
pulls)"`); `permission` is the team-wide level Gitea reports (`none` for a team
|
||||
that grants access per unit).
|
||||
|
||||
**JSON fields:** `access, all_repositories, can_create_repo, description, id,
|
||||
name, organization, permission, units`.
|
||||
|
||||
- `create <org> [<name>] [--name NAME] [--permission {read|write|admin}]
|
||||
[--unit repo.code=write,repo.wiki=read] [--all-repositories]
|
||||
[--can-create-repo] [-d description]`
|
||||
- `edit`, `delete`, `view`, `list`
|
||||
- `member {add|list|remove}` — adding a user to a team of an org also makes them
|
||||
an org member.
|
||||
- `repo {add|list|remove}` — repositories named alone (`service`) or `ORG/NAME`.
|
||||
|
||||
```bash
|
||||
gt team create acme developers --permission write
|
||||
gt team create acme/reviewers --unit repo.code=read,repo.pulls=write
|
||||
gt team member add acme/developers bob
|
||||
gt team repo add acme/developers service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## notification
|
||||
|
||||
```text
|
||||
gt notification <command>
|
||||
list mark-read mark-unread pin unpin view watch
|
||||
```
|
||||
|
||||
Across your whole inbox unless `-R`/`--this-repo` selects a repository. **IDs
|
||||
are notification thread IDs, not issue numbers.** `--type` is `issue`, `pull`,
|
||||
`commit`, or `repository`.
|
||||
|
||||
**JSON fields:** `id, number, pinned, repository, state, title, type, unread,
|
||||
updated_at, url`.
|
||||
|
||||
- `list [--status unread,read,pinned] [--type ...] [--since/--before when]
|
||||
[-L n] [--page n] [--this-repo]` (alias `ls`)
|
||||
- `view <id> [--this-repo]` — marks unread as read.
|
||||
- `mark-read [<id>...] [--all] [--status ...] [--before when] [--this-repo]`,
|
||||
`mark-unread`, `pin`, `unpin`.
|
||||
- `watch [--type ...] [--status ...] [--interval 5s] [--timeout d] [--json]` —
|
||||
streams as they arrive; on a terminal runs until Ctrl-C, otherwise stops after
|
||||
1 minute unless `--timeout` is given.
|
||||
|
||||
```bash
|
||||
gt notification list
|
||||
gt notification list --type pull --since 24h
|
||||
gt notification mark-read --all -R alice/project
|
||||
gt notification watch --type pull --json id,repository,title --timeout 0 | ./notify.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## search
|
||||
|
||||
```text
|
||||
gt search <command>
|
||||
issue pr repo
|
||||
```
|
||||
|
||||
Searches the selected instance within what your account can see. Words match
|
||||
titles and bodies.
|
||||
|
||||
- `search repo [<query>...] [--topic] [--owner OWNER] [--type {fork|source|mirror}]
|
||||
[--archived[=false]] [--private[=false]] [--sort {alpha|created|updated|size|id}]
|
||||
[--order {asc|desc}] [-L n] [--page n]`
|
||||
- `search issue [<query>...] [--assigned] [--authored] [--mentioned]
|
||||
[-A author] [-l label] [-m milestone] [--owner] [--team team] [-s state]
|
||||
[--since/--until when] [-L n] [--page n]` (alias `search issues`)
|
||||
- `search pr [<query>...]` — like issue plus `--review-requested`, `--reviewed`
|
||||
(instance-wide) (alias `search prs`).
|
||||
|
||||
`search issue`/`pr` JSON: `author, body, created_at, id, number, repository,
|
||||
state, title, type, updated_at, url`.
|
||||
|
||||
```bash
|
||||
gt search repo command line
|
||||
gt search repo --owner acme --archived
|
||||
gt search issue "login error"
|
||||
gt search issue crash -R alice/project --label bug --milestone v1.0
|
||||
gt search pr --review-requested
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## status
|
||||
|
||||
```text
|
||||
gt status [flags]
|
||||
```
|
||||
|
||||
Open issues and PRs assigned to you, reviews requested from you, and discussions
|
||||
mentioning you; in a clone it also lists failing Actions runs. `-R` scopes
|
||||
everything to one repository.
|
||||
|
||||
Flags: `--limit n` (1..100, default 30), `--runs` (default true).
|
||||
|
||||
JSON: `assigned_issues, failing_runs, host, mentions, pull_requests,
|
||||
repository, runs_included, runs_repository, user`.
|
||||
|
||||
```bash
|
||||
gt status
|
||||
gt status -R alice/project --runs=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## time
|
||||
|
||||
```text
|
||||
gt time <command>
|
||||
create delete list reset
|
||||
```
|
||||
|
||||
Log time on issues/PRs. Durations use `h`, `m`, `s` (`1h25m` or `"1h 25m"`).
|
||||
`create` aliases `add`/`log`; `list` aliases `ls`; `delete` aliases `rm`.
|
||||
|
||||
**JSON fields:** `created_at, id, issue_number, issue_title, issue_url,
|
||||
repository, seconds, user`.
|
||||
|
||||
- `create {issue} <duration>`
|
||||
- `list [--issue N|URL] [--mine] [--username user|@me] [--since/--until when]
|
||||
[--total] [-L n] [--page n]`
|
||||
- `delete {issue} <time-id> [-y]`
|
||||
- `reset {issue}` — delete your logged time on an issue.
|
||||
|
||||
```bash
|
||||
gt time create 12 1h25m
|
||||
gt time list --issue 12
|
||||
gt time list --mine --since 168h
|
||||
gt time delete 12 8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## webhook
|
||||
|
||||
```text
|
||||
gt webhook <command>
|
||||
create delete edit list view
|
||||
```
|
||||
|
||||
Scope: repository (default), organization (`--org`), your account (`--account`),
|
||||
or the instance (`--global`, administrators). Delivery URLs are shown without
|
||||
credentials/path unless `view --reveal-url`. Signing secrets and authorization
|
||||
headers are never shown.
|
||||
|
||||
**JSON fields:** `active, branch_filter, content_type, created_at, events, id,
|
||||
type, updated_at, url`.
|
||||
|
||||
- `create [<url>] [--url URL] [--type {gitea|gogs|slack|discord|dingtalk|telegram|msteams|feishu|matrix|wechatwork|packagist}]
|
||||
[--events push,issues,...] [--branch-filter glob] [--active[=false]]
|
||||
[--secret-file file|-] [--authorization-header-file file|-] [--config k=v]`
|
||||
- `list [-L n] [--page n]` (alias `ls`)
|
||||
- `view <id> [--reveal-url]`, `edit <id>`, `delete <id>`
|
||||
|
||||
Events include: `create, delete, fork, push, issues, issues_only,
|
||||
issue_assign, issue_label, issue_milestone, issue_comment, pull_request,
|
||||
pull_request_only, pull_request_assign, pull_request_label,
|
||||
pull_request_milestone, pull_request_comment, pull_request_review,
|
||||
pull_request_sync, pull_request_review_request, wiki, repository, release,
|
||||
package, status, workflow_run, workflow_job`.
|
||||
|
||||
```bash
|
||||
gt webhook create https://ci.example.com/hook --events push,pull_request --secret-file secret.txt
|
||||
gt webhook list --org acme
|
||||
gt webhook view 3 --reveal-url
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## wiki
|
||||
|
||||
```text
|
||||
gt wiki <command>
|
||||
create delete edit list revisions view
|
||||
```
|
||||
|
||||
**JSON fields (page):** `author, body, commit_count, footer, sha, sidebar,
|
||||
title, updated_at, url`; `list` returns `author, sha, title, updated_at, url`.
|
||||
|
||||
- `create [<title>] [-t title] [-b body] [-F file|-] [-e] [-m message]`
|
||||
- `edit <title> [...]`, `view <title>`, `delete <title>`,
|
||||
`list [-L n] [--page n]` (alias `ls`), `revisions <title>`
|
||||
|
||||
```bash
|
||||
gt wiki create "Getting Started" --body-file docs/start.md
|
||||
gt wiki list -R alice/project --json title,url
|
||||
gt wiki view Home
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ssh-key
|
||||
|
||||
```text
|
||||
gt ssh-key <command>
|
||||
create delete list view
|
||||
```
|
||||
|
||||
Manage the SSH public keys of your account. `create` aliases `add`; `list`
|
||||
aliases `ls`.
|
||||
|
||||
**JSON fields:** `created_at, fingerprint, id, key, read_only, title`.
|
||||
|
||||
- `create [<file>|-] [-t|--title TITLE]` — without a file, reads stdin.
|
||||
- `list [-L n] [--page n]`, `view <id>`, `delete <id>`
|
||||
|
||||
```bash
|
||||
gt ssh-key add ~/.ssh/id_ed25519.pub --title "Work laptop"
|
||||
gt ssh-key list --json title,fingerprint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## api
|
||||
|
||||
```text
|
||||
gt api <endpoint> [flags]
|
||||
```
|
||||
|
||||
Authenticated request to the instance API (path under `/api/v1`, or a full API
|
||||
URL). `{owner}`, `{repo}` expand to the selected repository; `{branch}` to the
|
||||
checked-out branch.
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-X, --method` | HTTP method (default GET; POST when a body is supplied) |
|
||||
| `-f, --raw-field k=v` | String parameter (query for GET/HEAD, JSON body otherwise) |
|
||||
| `-F, --field k=v` | Typed value: `true`/`false`/`null`, numbers, arrays, `@FILE`, `@-` |
|
||||
| `-H, --header name:value` | Request header |
|
||||
| `--input file` | Request body from a file, or `-` |
|
||||
| `--paginate`, `--max-pages n` | Follow next-page links / list paging |
|
||||
| `-i, --include` | Print status/headers to stderr |
|
||||
| `--output-file file` | Write the whole response to a file |
|
||||
| `--jq expr` | Filter each JSON response (jq not required) |
|
||||
| `--silent`, `--verbose` | No body / request+response to stderr |
|
||||
|
||||
Non-2xx responses print the body and fail with the HTTP status.
|
||||
|
||||
```bash
|
||||
gt api repos/{owner}/{repo}/issues -f state=open
|
||||
gt api user -F name=alice -F admin=true
|
||||
gt api repos/{owner}/{repo}/branches --paginate --jq '.[].name'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## config
|
||||
|
||||
```text
|
||||
gt config <command>
|
||||
get list path set
|
||||
```
|
||||
|
||||
Preferences live in `config.yml`, instance settings in `hosts.yml`, in the
|
||||
configuration directory (`$GITEA_CLI_CONFIG_DIR`, else `gitea-cli` under the XDG
|
||||
config dir). `gt config path` prints both files.
|
||||
|
||||
- `get <key> [--show-source]`, `list` (alias `ls`, add `--host` for instance
|
||||
settings), `set <key> <value> [--host URL] [--user NAME]`.
|
||||
- Keys: `default_host`, `git_protocol`, `editor`, `prompt`, `pager`, `browser`,
|
||||
`color`, `hyperlinks`, `markdown`, `remote`, `http_timeout`; instance:
|
||||
`user`, `ssh_host`, `insecure`, `git_protocol`, `oauth_client_id`, `headers`,
|
||||
`client_cert`, `client_key`; account: `ssh_key`, `ssh_agent`,
|
||||
`ssh_certificate_principal`, `ssh_key_fingerprint`.
|
||||
|
||||
```bash
|
||||
gt config path
|
||||
gt config set editor "code --wait"
|
||||
gt config set ssh_host git.example.com:2222 --host https://example.com
|
||||
gt config get default_host --show-source
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## alias
|
||||
|
||||
```text
|
||||
gt alias <command>
|
||||
delete list set
|
||||
```
|
||||
|
||||
An alias expands to a `gt` command with arguments, before `gt` runs it. `$1`,
|
||||
`$2`, ... take positional arguments; other arguments follow the expansion. No
|
||||
shell is run; built-ins always win.
|
||||
|
||||
- `set <name> <expansion> [--clobber]`
|
||||
- `list` (alias `ls`), `delete [<name>...] [--all]` (alias `rm`)
|
||||
|
||||
```bash
|
||||
gt alias set il "issue list --label bug"
|
||||
gt alias set review 'pr review $1 --approve'
|
||||
gt alias list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## completion
|
||||
|
||||
```text
|
||||
gt completion <command>
|
||||
bash fish powershell zsh
|
||||
```
|
||||
|
||||
Generate the shell completion script. Completion offers `--json` field names.
|
||||
|
||||
```bash
|
||||
gt completion bash > /etc/bash_completion.d/gt
|
||||
gt completion zsh > "${fpath[1]}/_gt"
|
||||
```
|
||||
@@ -0,0 +1,110 @@
|
||||
# Discovery: notifications, search, status, time
|
||||
|
||||
Finding and triaging work across repositories. `gt <cmd> --help` is
|
||||
authoritative. Global flags are in SKILL.md.
|
||||
|
||||
## notification
|
||||
|
||||
```text
|
||||
gt notification <command>
|
||||
list mark-read mark-unread pin unpin view watch
|
||||
```
|
||||
|
||||
Across your whole inbox unless `-R`/`--this-repo` selects a repository. **IDs
|
||||
are notification thread IDs, not issue numbers.** `--type` is `issue`, `pull`,
|
||||
`commit`, or `repository`.
|
||||
|
||||
**JSON fields:** `id, number, pinned, repository, state, title, type, unread,
|
||||
updated_at, url`.
|
||||
|
||||
- `list [--status unread,read,pinned] [--type ...] [--since/--before when]
|
||||
[-L n] [--page n] [--this-repo]` (alias `ls`)
|
||||
- `view <id> [--this-repo]` — marks unread as read.
|
||||
- `mark-read [<id>...] [--all] [--status ...] [--before when] [--this-repo]`,
|
||||
`mark-unread`, `pin`, `unpin`.
|
||||
- `watch [--type ...] [--status ...] [--interval 5s] [--timeout d] [--json]` —
|
||||
streams as they arrive; on a terminal runs until Ctrl-C, otherwise stops after
|
||||
1 minute unless `--timeout` is given.
|
||||
|
||||
```bash
|
||||
gt notification list
|
||||
gt notification list --type pull --since 24h
|
||||
gt notification mark-read --all -R alice/project
|
||||
gt notification watch --type pull --json id,repository,title --timeout 0 | ./notify.sh
|
||||
```
|
||||
|
||||
## search
|
||||
|
||||
```text
|
||||
gt search <command>
|
||||
issue pr repo
|
||||
```
|
||||
|
||||
Searches the selected instance within what your account can see. Words match
|
||||
titles and bodies.
|
||||
|
||||
- `search repo [<query>...] [--topic] [--owner OWNER] [--type {fork|source|mirror}]
|
||||
[--archived[=false]] [--private[=false]] [--sort {alpha|created|updated|size|id}]
|
||||
[--order {asc|desc}] [-L n] [--page n]`
|
||||
- `search issue [<query>...] [--assigned] [--authored] [--mentioned]
|
||||
[-A author] [-l label] [-m milestone] [--owner] [--team team] [-s state]
|
||||
[--since/--until when] [-L n] [--page n]` (alias `search issues`)
|
||||
- `search pr [<query>...]` — like issue plus `--review-requested`, `--reviewed`
|
||||
(instance-wide) (alias `search prs`).
|
||||
|
||||
`search issue`/`pr` JSON: `author, body, created_at, id, number, repository,
|
||||
state, title, type, updated_at, url`.
|
||||
|
||||
```bash
|
||||
gt search repo command line
|
||||
gt search repo --owner acme --archived
|
||||
gt search issue "login error"
|
||||
gt search issue crash -R alice/project --label bug --milestone v1.0
|
||||
gt search pr --review-requested
|
||||
```
|
||||
|
||||
## status
|
||||
|
||||
```text
|
||||
gt status [flags]
|
||||
```
|
||||
|
||||
Open issues and PRs assigned to you, reviews requested from you, and discussions
|
||||
mentioning you; in a clone it also lists failing Actions runs. `-R` scopes
|
||||
everything to one repository.
|
||||
|
||||
Flags: `--limit n` (1..100, default 30), `--runs` (default true).
|
||||
|
||||
JSON: `assigned_issues, failing_runs, host, mentions, pull_requests,
|
||||
repository, runs_included, runs_repository, user`.
|
||||
|
||||
```bash
|
||||
gt status
|
||||
gt status -R alice/project --runs=false
|
||||
```
|
||||
|
||||
## time
|
||||
|
||||
```text
|
||||
gt time <command>
|
||||
create delete list reset
|
||||
```
|
||||
|
||||
Log time on issues/PRs. Durations use `h`, `m`, `s` (`1h25m` or `"1h 25m"`).
|
||||
`create` aliases `add`/`log`; `list` aliases `ls`; `delete` aliases `rm`.
|
||||
|
||||
**JSON fields:** `created_at, id, issue_number, issue_title, issue_url,
|
||||
repository, seconds, user`.
|
||||
|
||||
- `create {issue} <duration>`
|
||||
- `list [--issue N|URL] [--mine] [--username user|@me] [--since/--until when]
|
||||
[--total] [-L n] [--page n]`
|
||||
- `delete {issue} <time-id> [-y]`
|
||||
- `reset {issue}` — delete your logged time on an issue.
|
||||
|
||||
```bash
|
||||
gt time create 12 1h25m
|
||||
gt time list --issue 12
|
||||
gt time list --mine --since 168h
|
||||
gt time delete 12 8
|
||||
```
|
||||
@@ -0,0 +1,189 @@
|
||||
# Instance: webhooks, wiki, keys, API, config, admin
|
||||
|
||||
Instance- and account-level commands. `gt <cmd> --help` is authoritative.
|
||||
Global flags are in SKILL.md.
|
||||
|
||||
## webhook
|
||||
|
||||
```text
|
||||
gt webhook <command>
|
||||
create delete edit list view
|
||||
```
|
||||
|
||||
Scope: repository (default), organization (`--org`), your account (`--account`),
|
||||
or the instance (`--global`, administrators). Delivery URLs often carry
|
||||
credentials, so `gt` shows them without user info and query (and without the path
|
||||
for chat services); `view --reveal-url` shows a URL whole. Signing secrets and
|
||||
authorization headers are never shown.
|
||||
|
||||
**JSON fields:** `active, branch_filter, content_type, created_at, events, id,
|
||||
type, updated_at, url`.
|
||||
|
||||
- `create [<url>] [--url URL] [--type {gitea|gogs|slack|discord|dingtalk|telegram|msteams|feishu|matrix|wechatwork|packagist}]
|
||||
[--events push,issues,...] [--branch-filter glob] [--active[=false]]
|
||||
[--secret-file file|-] [--authorization-header-file file|-] [--config k=v]`
|
||||
- `list [-L n] [--page n]` (alias `ls`)
|
||||
- `view <id> [--reveal-url]`, `edit <id>`, `delete <id>`
|
||||
|
||||
Events include: `create, delete, fork, push, issues, issues_only, issue_assign,
|
||||
issue_label, issue_milestone, issue_comment, pull_request, pull_request_only,
|
||||
pull_request_assign, pull_request_label, pull_request_milestone,
|
||||
pull_request_comment, pull_request_review, pull_request_sync,
|
||||
pull_request_review_request, wiki, repository, release, package, status,
|
||||
workflow_run, workflow_job`.
|
||||
|
||||
```bash
|
||||
gt webhook create https://ci.example.com/hook --events push,pull_request --secret-file secret.txt
|
||||
gt webhook list --org acme
|
||||
gt webhook view 3 --reveal-url
|
||||
```
|
||||
|
||||
## wiki
|
||||
|
||||
```text
|
||||
gt wiki <command>
|
||||
create delete edit list revisions view
|
||||
```
|
||||
|
||||
**JSON fields (page):** `author, body, commit_count, footer, sha, sidebar,
|
||||
title, updated_at, url`; `list` returns `author, sha, title, updated_at, url`.
|
||||
|
||||
- `create [<title>] [-t title] [-b body] [-F file|-] [-e] [-m message]`
|
||||
- `edit <title> [...]`, `view <title>`, `delete <title>`,
|
||||
`list [-L n] [--page n]` (alias `ls`), `revisions <title> [--page n]`
|
||||
|
||||
```bash
|
||||
gt wiki create "Getting Started" --body-file docs/start.md
|
||||
gt wiki list -R alice/project --json title,url
|
||||
gt wiki view Home
|
||||
```
|
||||
|
||||
## ssh-key
|
||||
|
||||
```text
|
||||
gt ssh-key <command>
|
||||
create delete list view
|
||||
```
|
||||
|
||||
Manage the SSH public keys of your account. `create` aliases `add`; `list`
|
||||
aliases `ls`.
|
||||
|
||||
**JSON fields:** `created_at, fingerprint, id, key, read_only, title`.
|
||||
|
||||
- `create [<file>|-] [-t|--title TITLE]` — without a file, reads stdin; the
|
||||
title defaults to the key comment, then the computer's name.
|
||||
- `list [-L n] [--page n]`, `view <id>`, `delete <id>`
|
||||
|
||||
```bash
|
||||
gt ssh-key add ~/.ssh/id_ed25519.pub --title "Work laptop"
|
||||
gt ssh-key list --json title,fingerprint
|
||||
```
|
||||
|
||||
## api
|
||||
|
||||
```text
|
||||
gt api <endpoint> [flags]
|
||||
```
|
||||
|
||||
Authenticated request to the instance API (path under `/api/v1`, or a full API
|
||||
URL). `{owner}`, `{repo}` expand to the selected repository; `{branch}` to the
|
||||
checked-out branch.
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-X, --method` | HTTP method (default GET; POST when a body is supplied) |
|
||||
| `-f, --raw-field k=v` | String parameter (query for GET/HEAD, JSON body otherwise) |
|
||||
| `-F, --field k=v` | Typed value: `true`/`false`/`null`, numbers, arrays, `@FILE`, `@-` |
|
||||
| `-H, --header name:value` | Request header |
|
||||
| `--input file` | Request body from a file, or `-` |
|
||||
| `--paginate`, `--max-pages n` | Follow next-page links / list paging |
|
||||
| `-i, --include` | Print status/headers to stderr |
|
||||
| `--output-file file` | Write the whole response to a file |
|
||||
| `--jq expr` | Filter each JSON response (jq not required) |
|
||||
| `--silent`, `--verbose` | No body / request+response to stderr |
|
||||
|
||||
Non-2xx responses print the body and fail with the HTTP status.
|
||||
|
||||
```bash
|
||||
gt api repos/{owner}/{repo}/issues -f state=open
|
||||
gt api user -F name=alice -F admin=true
|
||||
gt api repos/{owner}/{repo}/branches --paginate --jq '.[].name'
|
||||
```
|
||||
|
||||
## config
|
||||
|
||||
```text
|
||||
gt config <command>
|
||||
get list path set
|
||||
```
|
||||
|
||||
Preferences live in `config.yml`, instance settings in `hosts.yml`, in the
|
||||
configuration directory (`$GITEA_CLI_CONFIG_DIR`, else `gitea-cli` under the XDG
|
||||
config dir). `gt config path` prints both files.
|
||||
|
||||
- `get <key> [--show-source]`, `list` (alias `ls`, add `--host` for instance
|
||||
settings), `set <key> <value> [--host URL] [--user NAME]`.
|
||||
- Keys: `default_host`, `git_protocol`, `editor`, `prompt`, `pager`, `browser`,
|
||||
`color`, `hyperlinks`, `markdown`, `remote`, `http_timeout`; instance:
|
||||
`user`, `ssh_host`, `insecure`, `git_protocol`, `oauth_client_id`, `headers`,
|
||||
`client_cert`, `client_key`; account: `ssh_key`, `ssh_agent`,
|
||||
`ssh_certificate_principal`, `ssh_key_fingerprint`.
|
||||
|
||||
```bash
|
||||
gt config path
|
||||
gt config set editor "code --wait"
|
||||
gt config set ssh_host git.example.com:2222 --host https://example.com
|
||||
gt config get default_host --show-source
|
||||
```
|
||||
|
||||
## alias
|
||||
|
||||
```text
|
||||
gt alias <command>
|
||||
delete list set
|
||||
```
|
||||
|
||||
An alias expands to a `gt` command with arguments, before `gt` runs it. `$1`,
|
||||
`$2`, ... take positional arguments; other arguments follow the expansion. No
|
||||
shell is run; built-in commands always win over an alias of the same name.
|
||||
|
||||
- `set <name> <expansion> [--clobber]`
|
||||
- `list` (alias `ls`), `delete [<name>...] [--all]` (alias `rm`)
|
||||
|
||||
```bash
|
||||
gt alias set il "issue list --label bug"
|
||||
gt alias set review 'pr review $1 --approve'
|
||||
gt alias list
|
||||
```
|
||||
|
||||
## completion
|
||||
|
||||
```text
|
||||
gt completion <command>
|
||||
bash fish powershell zsh
|
||||
```
|
||||
|
||||
Generate the shell completion script. Completion offers `--json` field names.
|
||||
|
||||
```bash
|
||||
gt completion bash > /etc/bash_completion.d/gt
|
||||
gt completion zsh > "${fpath[1]}/_gt"
|
||||
```
|
||||
|
||||
## admin
|
||||
|
||||
```text
|
||||
gt admin <command>
|
||||
user (list, view, create, edit, delete)
|
||||
```
|
||||
|
||||
Instance administration; requires an administrator account. (`--sudo user` on
|
||||
other commands acts as another user.) JSON: `active, admin, created_at,
|
||||
description, email, full_name, id, location, prohibit_login, restricted, url,
|
||||
username, visibility, website`.
|
||||
|
||||
```bash
|
||||
gt admin user list
|
||||
gt admin user list --query bob
|
||||
gt admin user create alice --email alice@example.com
|
||||
```
|
||||
@@ -0,0 +1,142 @@
|
||||
# Issues, labels, milestones
|
||||
|
||||
Issue management plus repository/organization labels and milestones.
|
||||
`gt <cmd> --help` is authoritative. Global/repository-selection flags are in
|
||||
SKILL.md.
|
||||
|
||||
## issue
|
||||
|
||||
```text
|
||||
gt issue <command>
|
||||
attachment close comment create edit list reopen timeline view
|
||||
```
|
||||
|
||||
`issue list` aliases `issue ls`; `issue create` aliases `issue new`.
|
||||
|
||||
**Issue argument:** `123`, `#123`, a URL, or `OWNER/REPO#123`.
|
||||
|
||||
**JSON fields (issue):** `assignees, author, body, comments, created_at,
|
||||
due_date, id, kind, labels, milestone, number, ref, state, title, updated_at,
|
||||
url`. `view`/`edit` add `blocked_by, blocks` (extra requests, only when named).
|
||||
|
||||
Gitea lists pull requests among issues, so most issue commands also accept a PR
|
||||
number.
|
||||
|
||||
### list
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-s, --state {open\|closed\|all}` | default `open` |
|
||||
| `-a, --assignee`, `-A, --author`, `--mentions` | `@me` for yourself |
|
||||
| `--no-assignee` | only issues without an assignee |
|
||||
| `-l, --label names`, `-m, --milestone titles` | filters |
|
||||
| `--kind {issues\|pulls\|all}` | include PRs |
|
||||
| `-S, --search text` | search titles and bodies |
|
||||
| `--since`, `--until` | updated window (date, timestamp, or duration ago) |
|
||||
| `-L, --limit n` (1..1000, default 30), `--page n` | pagination |
|
||||
| `-w, --web` | open in browser |
|
||||
|
||||
```bash
|
||||
gt issue list --label bug --state all
|
||||
gt issue list --assignee @me --json number,title
|
||||
gt issue list --kind all --milestone v1.0 | cut -f1,2
|
||||
```
|
||||
|
||||
### create
|
||||
|
||||
`-t/--title`, `-b/--body`, `-F/--body-file file|-`, `-e/--editor`,
|
||||
`-a/--assignee login`, `-l/--label name` (prefix `repo:`/`org:` to disambiguate),
|
||||
`-m/--milestone`, `-p/--project`, `--ref`, `--deadline DATE`,
|
||||
`-T/--template name`, `--attachment File`, `-w/--web`.
|
||||
|
||||
Without flags on a terminal, a form asks for title and body, then optionally
|
||||
assignees, a milestone, labels and a due date. Gitea applies
|
||||
labels/milestone/assignees/deadline only to users with issue write access;
|
||||
otherwise `gt` reports the left-out fields and fails.
|
||||
|
||||
```bash
|
||||
gt issue create --title "Crash on start" --body "Steps..." \
|
||||
--label bug --milestone v1.0
|
||||
gt issue create --template "Bug report"
|
||||
```
|
||||
|
||||
### edit
|
||||
|
||||
Adds/removes relative to current values, or replaces with `--set-*`:
|
||||
`--add-label`, `--remove-label`, `--set-labels`, `--add-assignee`,
|
||||
`--remove-assignee`, `--set-assignees`, `-m/--milestone`,
|
||||
`--remove-milestone`, `--add-blocked-by`, `--remove-blocked-by`,
|
||||
`--add-project`, `--remove-project`, `-t/--title`, `-b/--body`,
|
||||
`-F/--body-file`, `-e/--editor`, `--ref`, `--deadline`. Accepts multiple issues.
|
||||
|
||||
```bash
|
||||
gt issue edit 12 --title "Crash on start" --add-label bug
|
||||
gt issue edit 12 13 --add-assignee @me --milestone v1.0
|
||||
gt issue edit 12 --add-blocked-by 9
|
||||
```
|
||||
|
||||
### close / reopen / comment / timeline / view / attachment
|
||||
|
||||
- `close {N}... [-c comment]`, `reopen {N}...`
|
||||
- `comment {N} [-b text] [-F file] [-e] [--edit-last] [--delete-last]
|
||||
[--attachment File]`; subcommands `list|view|edit|delete`. JSON: `author,
|
||||
body, created_at, id, issue_number, updated_at, url`.
|
||||
- `timeline {N} [-L n] [--page n]` — comments and changes, oldest first.
|
||||
- `view {N} [-c|--comments] [-w]`
|
||||
- `attachment {list|view|upload|download|edit|delete}`
|
||||
|
||||
```bash
|
||||
gt issue view 12 --comments
|
||||
gt issue comment 12 --body "Fixed in #14"
|
||||
gt issue close 12 13 --comment "Done in #14"
|
||||
```
|
||||
|
||||
## label
|
||||
|
||||
```text
|
||||
gt label <command>
|
||||
create delete edit export import list
|
||||
```
|
||||
|
||||
Scope with `--org organization` for organization labels; otherwise the
|
||||
repository's. Addressed by name or ID. JSON: `color, description, exclusive,
|
||||
id, is_archived, name`.
|
||||
|
||||
- `create <name> [-c color] [-d description] [--exclusive] [--archived]
|
||||
[-f/--force]` — random color without `-c`; `--force` updates on name clash.
|
||||
- `list`, `edit`, `delete`
|
||||
- `export [-O|--output file]` and `import <file> [-f|--force]` — a label file,
|
||||
one label per line: `#color name ;description ;flags`. `gt label export`
|
||||
writes this format; Gitea label templates use it. `-` reads/writes stdin.
|
||||
|
||||
```bash
|
||||
gt label create bug --color d73a4a --description "Something is broken"
|
||||
gt label create "priority/high" --exclusive
|
||||
gt label export --org acme --output labels.txt
|
||||
gt label export -R alice/old | gt label import - -R alice/new
|
||||
```
|
||||
|
||||
## milestone
|
||||
|
||||
```text
|
||||
gt milestone <command>
|
||||
close create delete edit issue list reopen view
|
||||
```
|
||||
|
||||
`milestone list` aliases `milestone ls`; `milestone create` aliases
|
||||
`milestone new`. Addressed by title or ID. `milestone issue` manages the
|
||||
issues/PRs in it. JSON: `closed_issues, description, due_on, id, open_issues,
|
||||
state, title`.
|
||||
|
||||
- `create [<title>] [-t title] [-d description] [-F desc-file] [-e]
|
||||
[--deadline date] [--state {open|closed}] [-f/--force]` — `--force` updates an
|
||||
existing milestone of the same title.
|
||||
- `list [-s {open|closed|all}] [-L n] [--page n]`, `view`, `edit`, `close`,
|
||||
`reopen`, `delete`
|
||||
- `issue list <milestone>` etc.
|
||||
|
||||
```bash
|
||||
gt milestone create v1.0 --deadline 2026-12-31 --description "First release"
|
||||
gt milestone list --state open
|
||||
gt milestone issue list v1.0
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
# Organizations and teams
|
||||
|
||||
Organization management and team access. `gt <cmd> --help` is authoritative.
|
||||
Global flags are in SKILL.md.
|
||||
|
||||
## org
|
||||
|
||||
```text
|
||||
gt org <command>
|
||||
create delete edit list member view
|
||||
```
|
||||
|
||||
Organizations you belong to.
|
||||
|
||||
- `list`, `view <org>`
|
||||
- `create <name> [-d description] [--full-name NAME] [--location LOC]
|
||||
[--website URL] [--visibility {public|limited|private}]
|
||||
[--repo-admins-can-change-team-access[=false]]`
|
||||
- `edit <org>`, `delete <org>`
|
||||
- `member {list|add|remove}` — `member list <org> [--public]`; Gitea lists every
|
||||
membership as public to administrators, so for them `gt` checks each one's
|
||||
visibility (one request per member) unless the output omits it.
|
||||
|
||||
JSON: `description, full_name, id, location, name, repo_admin_change_team_access,
|
||||
visibility, website`.
|
||||
|
||||
```bash
|
||||
gt org list
|
||||
gt org create acme --full-name "ACME Corp"
|
||||
gt org create acme-internal --visibility private
|
||||
gt org member list acme --public
|
||||
```
|
||||
|
||||
## team
|
||||
|
||||
```text
|
||||
gt team <command>
|
||||
create delete edit list member repo view
|
||||
```
|
||||
|
||||
Teams grant members access to an organization's repositories. In JSON, `access`
|
||||
is the effective access shown in text (e.g. `write`, `"write (code, issues,
|
||||
pulls)"`); `permission` is the team-wide level Gitea reports (`none` for a team
|
||||
that grants access per unit).
|
||||
|
||||
**JSON fields:** `access, all_repositories, can_create_repo, description, id,
|
||||
name, organization, permission, units`.
|
||||
|
||||
- `create <org> [<name>] [--name NAME] [--permission {read|write|admin}]
|
||||
[--unit repo.code=write,repo.wiki=read] [--all-repositories]
|
||||
[--can-create-repo] [-d description]` — `--permission` grants every repository
|
||||
unit; `--unit` sets single units and overrides `--permission` per unit.
|
||||
- `edit <team>`, `delete <team>`, `view <team>`, `list <org>`
|
||||
- `member {add|list|remove} <team> [<username>...]` — a team is `ORG/TEAM` or a
|
||||
numeric ID; adding a user also makes them an org member.
|
||||
- `repo {add|list|remove} <team> [<repository>...]` — repositories named alone
|
||||
(`service`) or `ORG/NAME`.
|
||||
|
||||
```bash
|
||||
gt team create acme developers --permission write
|
||||
gt team create acme/reviewers --unit repo.code=read,repo.pulls=write
|
||||
gt team member add acme/developers bob
|
||||
gt team repo add acme/developers service
|
||||
```
|
||||
@@ -0,0 +1,133 @@
|
||||
# Pull requests (`gt pr`)
|
||||
|
||||
Pull requests, including reviews, checks, diff, checkout and merge.
|
||||
`gt <cmd> --help` is authoritative. Global/repository-selection flags are in
|
||||
SKILL.md.
|
||||
|
||||
```text
|
||||
gt pr <command>
|
||||
attachment checkout checks clean close comment create diff
|
||||
edit list merge ready reopen review status timeline view
|
||||
```
|
||||
|
||||
`pr list` aliases `pr ls`; `pr create` aliases `pr new`; `pr checkout` aliases
|
||||
`pr co`.
|
||||
|
||||
**PR argument:** `13`, `#13`, a URL, or a head branch name (e.g. `feature/login`
|
||||
or `bob:feature/login`). Without one, the PR of the current branch.
|
||||
|
||||
**JSON fields (PR):** `assignees, author, base, body, comments, created_at,
|
||||
draft, due_date, head, head_remote_deleted, head_repo, head_sha, id, labels,
|
||||
merge_commit_sha, mergeable, merged, merged_at, merged_by, milestone, number,
|
||||
review_decision, reviewer_teams, reviewers, reviews, state, title, updated_at,
|
||||
url`. On `list`, `reviewers`, `reviewer_teams`, `reviews`, `review_decision` and
|
||||
`merged_by` cost extra requests and are fetched only when named.
|
||||
|
||||
## list
|
||||
|
||||
`-s, --state {open|closed|merged|all}` (default `open`), `-a/--assignee`,
|
||||
`-A/--author`, `--no-assignee`, `-l/--label`, `-m/--milestone`,
|
||||
`-B/--base branch`, `-H/--head branch|OWNER:BRANCH`, `-d/--draft`,
|
||||
`-S/--search`, `--sort`, `-L/--limit`, `--page`, `-w/--web`.
|
||||
|
||||
`review_decision` is `changes_requested`, `approved`, `review_required` or
|
||||
empty.
|
||||
|
||||
```bash
|
||||
gt pr list --author @me --state all
|
||||
gt pr list --json number,title,head --jq '.[] | select(.head == "feature/login")'
|
||||
```
|
||||
|
||||
## create
|
||||
|
||||
`--fill` (title/body from commits), `-t/--title`, `-b/--body`,
|
||||
`-F/--body-file`, `-e/--editor`, `-B/--base`, `-H/--head`, `-d/--draft`,
|
||||
`-a/--assignee`, `-r/--reviewer`, `--reviewer-team`, `-l/--label`,
|
||||
`-m/--milestone`, `-p/--project`, `--deadline`, `--attachment`,
|
||||
`--allow-maintainer-edits` (default true), `--agit` (+ `--topic`), `-w/--web`,
|
||||
`-y/--yes`.
|
||||
|
||||
Creates from the current branch, or `--head`. Pushes a not-yet-remote branch
|
||||
after a confirmation (`--yes` in CI). A branch without a same-named upstream
|
||||
goes to the fork when origin is a fork, or to the only remote of your own fork;
|
||||
otherwise to the repository's remote. Any flag skips the interactive questions;
|
||||
the title is then `--title`, else the commit message of a single-commit branch,
|
||||
else the branch name.
|
||||
|
||||
```bash
|
||||
gt pr create --fill --yes
|
||||
gt pr create -t "Add login" -b "Closes #1" -B develop -r carol -l enhancement
|
||||
```
|
||||
|
||||
## checkout / diff / checks
|
||||
|
||||
- `checkout {N|url|branch} [-b branch] [--detach] [--update]` — local branch
|
||||
tracking the head, so `git push` updates it. `--update` fast-forwards an
|
||||
existing branch and rejects divergence. JSON: `branch, commit, detached,
|
||||
remote, tracking`.
|
||||
- `diff [{N|url|branch}] [--name-only] [--color auto|always|never] [-w]` — clean
|
||||
diff when piped (`gt pr diff 13 | git apply`); colored and paged on a
|
||||
terminal.
|
||||
- `checks [{N|url|branch}] [--watch] [--interval d] [--timeout d] [-w]` — latest
|
||||
status of each check. Exits **8** while pending, **1** on failure. JSON:
|
||||
`created_at, description, id, name, sha, state, updated_at, url`.
|
||||
|
||||
```bash
|
||||
gt pr checkout 13 --update
|
||||
gt pr diff 13 | git apply
|
||||
gt pr checks 13 --watch && gt pr merge 13
|
||||
```
|
||||
|
||||
## merge
|
||||
|
||||
`-s/--method {merge|rebase|rebase-merge|squash|fast-forward-only}` (default:
|
||||
repo's style), shortcuts `--merge`, `--rebase`, `--squash`, `--auto`
|
||||
(merge once required checks succeed), `-d/--delete-branch` (also deletes the
|
||||
local head branch when checked out, switching to the base), `-t/--title`,
|
||||
`-b/--message`, `-F/--message-file`, `-e/--editor`.
|
||||
|
||||
```bash
|
||||
gt pr merge 13 --squash --delete-branch
|
||||
gt pr merge 13 --auto --yes
|
||||
```
|
||||
|
||||
## review
|
||||
|
||||
Choose the type with `-a/--approve`, `-r/--request-changes` (needs a body), or
|
||||
`-c/--comment`. Flags: `-b/--body`, `-F/--body-file`, `-e/--editor`,
|
||||
`--pending` (save for later), `--commit sha`,
|
||||
`--comments-file file` (JSON array of `path`, `body`, `new_position` or
|
||||
`old_position`), `-y/--yes`. Subcommands: `create, list, view, delete, submit,
|
||||
request, cancel-request, comments, reply, resolve, unresolve, dismiss,
|
||||
undismiss`. JSON: `author, body, comments_count, commit, dismissed, id,
|
||||
official, stale, state, submitted_at, team, url`.
|
||||
|
||||
On a terminal, no type opens an interactive review that can annotate the diff in
|
||||
your editor (lines you start with `#` become inline comments).
|
||||
|
||||
```bash
|
||||
gt pr review --approve
|
||||
gt pr review 13 -r -b "Please hash the password"
|
||||
gt pr review 13 --pending --comments-file inline.json
|
||||
gt pr review submit 13 --approve
|
||||
```
|
||||
|
||||
## status / clean / ready / comment / view / edit
|
||||
|
||||
- `status [--limit n]` — current branch's PR with checks/review, then your
|
||||
authored/assigned/review-requested PRs. JSON: `assigned, authored,
|
||||
current_branch, review_requested`.
|
||||
- `clean [{...}] [--ignore-sha]` — delete the branch of a merged/closed PR
|
||||
locally and on Gitea. JSON: `default_branch, local_branch, remote,
|
||||
remote_branch, remote_deleted, remote_skip_reason, remote_skipped`.
|
||||
- `ready [{...}] [--undo]` — mark ready/back to draft (toggles `WIP:`/`[WIP]`).
|
||||
- `comment [{...}]` — like `issue comment` (JSON: `author, body, created_at, id,
|
||||
issue_number, updated_at, url`); subcommands `list|view|edit|delete`.
|
||||
- `view [{...}] [-c|--comments] [-w]`, `edit`, `close`, `reopen`, `timeline`,
|
||||
`attachment`.
|
||||
|
||||
```bash
|
||||
gt pr status
|
||||
gt pr ready
|
||||
gt pr clean 13
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
# Releases (`gt release`)
|
||||
|
||||
Releases and their assets. `gt <cmd> --help` is authoritative. Global/repository
|
||||
selection flags are in SKILL.md.
|
||||
|
||||
```text
|
||||
gt release <command>
|
||||
asset create delete download edit list publish upload view
|
||||
```
|
||||
|
||||
`release list` aliases `release ls`; `release create` aliases `release new`.
|
||||
|
||||
**JSON fields:** `assets, author, body, created_at, draft, id, prerelease,
|
||||
published_at, tag, target, title, url`.
|
||||
|
||||
## create
|
||||
|
||||
`gt release create [<tag>] [<file>...]` with `-t/--title`, `-n/--notes`,
|
||||
`-F/--notes-file`, `-e/--editor`, `-d/--draft`, `-p/--prerelease`,
|
||||
`--target branch|commit` (for a new tag), `--asset File`, `--verify-tag`.
|
||||
Files after the tag are uploaded as assets; the title defaults to the tag.
|
||||
|
||||
`gt` **never pushes**: commits and tags that exist only in your clone are not on
|
||||
the server, so push them first (`git push <remote> <tag>`). A tag that exists
|
||||
only in your clone is refused unless `--target` says where Gitea creates it;
|
||||
`--verify-tag` refuses any tag not on the server yet.
|
||||
|
||||
```bash
|
||||
gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md
|
||||
gt release create v1.1.0-rc1 --target release/1.1 --draft --prerelease --title "1.1 RC 1"
|
||||
```
|
||||
|
||||
## upload / download
|
||||
|
||||
- `upload <tag> <file>... [--name NAME] [--clobber]` — an asset of the same name
|
||||
is replaced only with `--clobber`. JSON per asset: `created_at,
|
||||
download_count, id, name, size, url`.
|
||||
- `download [<tag>] [<asset>...] [-A|--archive {zip|tar.gz}] [-p|--pattern glob]
|
||||
[-D|--dir dir] [-O|--output file|-] [--clobber] [--skip-existing]` — latest
|
||||
release without a tag; `--archive` downloads source code instead.
|
||||
|
||||
```bash
|
||||
gt release upload v1.0.0 dist/tool-linux --clobber
|
||||
gt release download v1.0.0 --pattern '*linux*' --dir dist
|
||||
gt release download v1.0.0 --archive zip
|
||||
```
|
||||
|
||||
## asset / publish / edit / delete / list / view
|
||||
|
||||
- `asset {list|upload|download|delete|...}` — manage assets individually.
|
||||
- `publish <tag>...` — publish draft releases.
|
||||
- `edit <tag>...`, `delete <tag>...`, `list [-L n] [--page n]`,
|
||||
`view [<tag>] [-w]` (latest without a tag).
|
||||
@@ -0,0 +1,84 @@
|
||||
# Repositories (`gt repo`, `gt branch`)
|
||||
|
||||
Repository management plus server-side branches. `gt <cmd> --help` is
|
||||
authoritative. Global/repository-selection flags are in SKILL.md.
|
||||
|
||||
## repo
|
||||
|
||||
```text
|
||||
gt repo <command>
|
||||
archive clone create delete deploy-key edit fork list migrate
|
||||
rename set-default sync transfer unarchive view
|
||||
```
|
||||
|
||||
`repo list` aliases `repo ls`; `repo create` aliases `repo new`.
|
||||
|
||||
**Repository argument** (where accepted): `NAME` (one of yours), `OWNER/NAME`,
|
||||
`HOST/OWNER/NAME`, or a URL. Without one, the current clone's repository.
|
||||
|
||||
**JSON fields (repo objects):** `actions_enabled, archived, clone_url,
|
||||
default_branch, description, empty, fork, forks_count, full_name, id, mirror,
|
||||
mirror_interval, name, open_issues_count, open_pr_count, original_url, parent,
|
||||
private, ssh_url, stars_count, template, topics, updated_at, url, website`.
|
||||
|
||||
### Key subcommands
|
||||
|
||||
- `list [<owner>] [--starred] [--watched] [--type {fork|source|mirror}] [-L n]
|
||||
[--page n]`
|
||||
- `view [<repo>] [-b branch] [-w]` — description, state, counts, clone URLs,
|
||||
then the rendered README.
|
||||
- `create [<name>] [--org ORG] [--private|--public] [--auto-init]
|
||||
[--readme TMPL] [--gitignores TMPL] [--license TMPL] [--default-branch NAME]
|
||||
[-d DESC] [--template OWNER/REPO] [--source DIR] [--push] [--clone]
|
||||
[--as-template]` — `--source`/`--push` publish a local repo;
|
||||
`--template` copies another; `--auto-init` adds a first commit.
|
||||
- `clone <repo> [<dir>] [-- <gitflags>] [-d depth] [--no-upstream]
|
||||
[-u upstream-name]` — a fork's parent is added as `upstream`; a mirror's
|
||||
source as `source`. `gt` commands in the clone then target the parent.
|
||||
- `fork [<repo>] [--clone] [--org ORG] [--remote] [--remote-name NAME]
|
||||
[--fork-name NAME] [-- <gitflags>]` — inside a clone, `--remote` adds the fork
|
||||
as `origin` and renames the old `origin` to `upstream`.
|
||||
- `sync [<repo>] [-b branch]` — fast-forward a local branch (default: default
|
||||
branch) from its remote without switching; for a fork/mirror without a local
|
||||
remote, updates it on the server. JSON: `branch, commit, previous, remote`.
|
||||
- `set-default [<repo>] [-u|--unset] [-v|--view]` — store `gt.repository` in the
|
||||
clone so commands target it instead of the git remotes.
|
||||
- `edit`, `delete`, `rename`, `transfer`, `archive`, `unarchive`, `migrate`,
|
||||
`deploy-key`.
|
||||
|
||||
```bash
|
||||
gt repo list --starred --json full_name,url
|
||||
gt repo create project --private --auto-init --license MIT
|
||||
gt repo create acme/service --template acme/service-template
|
||||
gt repo create project --source . --push
|
||||
gt repo fork alice/project --clone -- --depth 1
|
||||
gt repo sync --branch release/1.0
|
||||
gt repo sync bob/project # update the fork on the server
|
||||
```
|
||||
|
||||
## branch
|
||||
|
||||
```text
|
||||
gt branch <command>
|
||||
create delete list protect rename unprotect view
|
||||
```
|
||||
|
||||
Server-side branches (use `git` for local branches). JSON: `can_merge,
|
||||
can_push, message, name, protected, required_approvals, sha, updated_at`.
|
||||
|
||||
- `create <branch> [-s|--source branch|tag|commit]` — default branch unless
|
||||
`--source` names one.
|
||||
- `list`, `view <branch> [-w]`, `rename`, `delete`
|
||||
- `protect <branch>... [--pattern glob] [--required-approvals n]
|
||||
[--allow-push user|ORG/TEAM] [--status-check name] [--dismiss-stale-approvals]
|
||||
[--block-on-rejected-reviews]` — by default nobody pushes directly and PRs
|
||||
need one approval. `--pattern` protects every matching branch; existing rules
|
||||
change only the named settings.
|
||||
- `unprotect <branch>...`
|
||||
|
||||
```bash
|
||||
gt branch list
|
||||
gt branch create release/1.0 --source main
|
||||
gt branch protect main --required-approvals 2 --status-check ci/build
|
||||
gt branch protect --pattern 'release/*' --allow-push acme/release
|
||||
```
|
||||
@@ -0,0 +1,74 @@
|
||||
# Workflows (recipes)
|
||||
|
||||
End-to-end recipes for common tasks. For per-command flags and JSON fields, read
|
||||
the group file in this directory (listed in SKILL.md's command map). All flags
|
||||
are from `gt` 0.1.0; `gt <cmd> --help` is authoritative.
|
||||
|
||||
## Issue lifecycle
|
||||
|
||||
```bash
|
||||
gt issue list --assignee @me --state open
|
||||
gt issue view 12 --comments
|
||||
gt issue create --title "Crash on start" --body "Steps..." --label bug --milestone v1.0
|
||||
gt issue edit 12 --add-label triage --add-assignee @me
|
||||
gt issue comment 12 --body "Fixed in #14"
|
||||
gt issue close 12 --comment "Done in #14"
|
||||
```
|
||||
|
||||
## Pull requests: create → checks → review → merge
|
||||
|
||||
```bash
|
||||
gt pr create --fill # push branch, open PR, title/body from commits
|
||||
gt pr create --fill --yes # non-interactive: also push without asking
|
||||
gt pr list --author @me --state all
|
||||
gt pr checkout 13 --update # local branch tracking the PR head
|
||||
gt pr diff 13 | git apply # pipe clean diff (git apply works)
|
||||
gt pr checks 13 --watch # waits; exit 8 while pending, 1 if a check failed
|
||||
gt pr review --approve
|
||||
gt pr review 13 --request-changes -b "Please hash the password"
|
||||
gt pr merge 13 --squash --delete-branch
|
||||
```
|
||||
|
||||
A branch that is not on the remote is pushed first, after a confirmation; in CI
|
||||
pass `--yes` (or `--no-input` will fail rather than prompt). See
|
||||
[pull-requests.md](pull-requests.md) for fork handling.
|
||||
|
||||
## Actions: dispatch, watch, logs, artifacts
|
||||
|
||||
```bash
|
||||
gt workflow list
|
||||
gt workflow run deploy.yml --ref main --field env=staging
|
||||
gt run list --workflow CI --branch main --status failure
|
||||
gt run watch 34 --timeout 10m && echo deployed
|
||||
gt run view 34 --log
|
||||
gt run logs 34 --job build --follow
|
||||
gt run download 34 --name build --dir dist
|
||||
gt secret set DEPLOY_TOKEN
|
||||
```
|
||||
|
||||
`gt run watch` and `gt workflow run --follow` **fail when the run completes
|
||||
without success**, so they chain well with `&&`. See [actions.md](actions.md).
|
||||
|
||||
## Releases
|
||||
|
||||
```bash
|
||||
gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md
|
||||
gt release list
|
||||
gt release upload v1.0.0 dist/tool-darwin --clobber
|
||||
gt release download v1.0.0
|
||||
```
|
||||
|
||||
`gt release create` never pushes a tag: push it first (`git push origin v1.0.0`)
|
||||
or let Gitea create it with `--target`. See [releases.md](releases.md).
|
||||
|
||||
## Fork, clone and keep in sync
|
||||
|
||||
```bash
|
||||
gt repo fork --remote # inside a clone: add fork as origin, rename old origin to upstream
|
||||
gt repo clone alice/project src --depth 1
|
||||
gt repo sync # fast-forward the default branch from its remote
|
||||
gt repo sync bob/project # fork without a local remote: update it on the server
|
||||
```
|
||||
|
||||
In a clone with both `upstream` and `origin`, `gt` targets `upstream` (like
|
||||
`gh`). See [repos.md](repos.md).
|
||||
Reference in new issue
Block a user