raucao
8b5c216563
Cover the 1.0.0 command surface and stability guarantees: - New reference files: projects.md, runners.md, extensions.md - New commands: browse, project, runner, extension, upgrade, pr backport, pr update-branch, pr list --local, pr merge --method manually-merged, issue move, issue/pr comment attachment, webhook test - Global --csv output; exit codes 5 (run watch failed) and 6 (--expect-head) - Interactive edit forms for pr/label/release edit - Fix fork flag (--add-remote), clone flag (--upstream-remote-name), and org member subcommands (add -> conceal/publicize) - tea is archived; gt is the official successor; migration guide linked - Semver: 1.x keeps commands/flags/JSON fields/exit codes stable - Bump metadata/README to gt 1.0.0
130 lines
4.4 KiB
Markdown
130 lines
4.4 KiB
Markdown
# 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` 1.0.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 list --local # which local branches belong to a merged/closed PR
|
|
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 update-branch 13 --rebase # bring the base branch in
|
|
gt pr merge 13 --squash --delete-branch
|
|
gt pr clean 13 # delete the branch of a merged/closed PR
|
|
```
|
|
|
|
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.
|
|
|
|
## Backport a merged PR
|
|
|
|
```bash
|
|
gt pr backport 42 --to release/v1.2 --to release/v1.1 --yes
|
|
# On conflict, resolve yourself:
|
|
gt pr backport 42 --to release/v1.1 --keep
|
|
git add . && git cherry-pick --continue
|
|
gt pr backport --continue
|
|
```
|
|
|
|
## Mark a PR merged outside Gitea
|
|
|
|
The repository must allow it (`gt repo edit --allow-manual-merge`).
|
|
|
|
```bash
|
|
git push origin main # the commit that merged the PR
|
|
gt pr merge 13 --method manually-merged --commit 4b825dc --delete-branch
|
|
```
|
|
|
|
## 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 watch 34 --expect-head HEAD # exit 6 if the run is for another commit
|
|
gt run view 34 --log
|
|
gt run logs 34 --job build --follow
|
|
gt run logs 34 --failed --tail 50
|
|
gt run download 34 --name build --dir dist
|
|
gt secret set DEPLOY_TOKEN
|
|
```
|
|
|
|
`gt run watch` and `gt workflow run --follow` **exit 5 when the run completes
|
|
without success**, so they chain well with `&&`; exit 1 means `gt` itself
|
|
failed. See [actions.md](actions.md). Runners are in [runners.md](runners.md).
|
|
|
|
## Projects
|
|
|
|
```bash
|
|
gt project create Roadmap --template basic_kanban
|
|
gt project list --state open
|
|
gt issue move 47 to "In progress"
|
|
```
|
|
|
|
## 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 --add-remote # inside a clone: add fork as origin, rename old origin to upstream
|
|
gt repo clone alice/project src --depth 1
|
|
gt repo clone alice/project --find-instance # pick the instance that has it
|
|
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).
|
|
|
|
## Extensions and keeping `gt` current
|
|
|
|
```bash
|
|
gt extension install alice/gt-hello
|
|
gt extension list
|
|
gt upgrade # self-upgrade (verified checksum)
|
|
```
|
|
|
|
See [extensions.md](extensions.md).
|
|
|
|
## Machine-readable output: JSON and CSV
|
|
|
|
Text output is for people and may change; scripts should use `--json`/`--jq` or
|
|
`--csv`.
|
|
|
|
```bash
|
|
gt issue list --state all --json number,title,state
|
|
gt issue list --state all --csv number,title,state > issues.csv
|
|
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
|
|
```
|