gt-tool

CLI tools for interacting with the Gitea API. Use interactively to talk to your Gitea instance, or automatically via a CI/CD pipeline.

Usage

Usage: gt-tool [OPTIONS] <COMMAND>

Commands:
  list-releases   
  create-release  
  upload-release  
  help            Print this message or the help of the given subcommand(s)

Options:
  -u, --url <GITEA_URL>    [env: GTTOOL_GITEA_URL=]
  -o, --owner <OWNER>      [env: GTTOOL_OWNER=]
  -r, --repo <REPO>        [env: GTTOOL_REPO=]
  -p, --project <PROJECT>  Path to project (relative or absolute). Used to override configuration selection.
  -h, --help               Print help
  -V, --version            Print version

Authentication

Authentication is token-based via environment variable RELEASE_KEY_GITEA.

Ensure your token has the appropriate access for your usage. This depends on what you're doing and how your Gitea instance is configured, so you'll have to figure it out for yourself.

Most likely, you will need a token with "repository: read-and-write" permissions. See Gitea's documentation on token scopes for more.

<GITEA_URL>:

The Gitea server URL must be provided with --url or -u on the command line, or via the environment variable GTTOOL_GITEA_URL. Use the base URL for your Gitea instance.

E.g.: Using the Gitea org's demo instance, it would be: --url "https://demo.gitea.com/"

<REPO>:

The repository name must be provided with --repo or -u on the command line, or via the environment variable GTTOOL_GITEA_FQRN ("fully qualified repo name"). Use the format <owner>/<repo>, which is the route immediately following the GITEA_URL base. This is how GitHub and Gitea identify repos in the URL, and how Golang locates it's modules, so this tool does the same.

E.g.: --repo "go-gitea/gitea" would name the Gitea repo belonging to the go-gitea organization.

<PROJECT>

Override the default (current-directory) project name when searching through the config files for this project's settings.

See configuration for details on format and file locations.

<COMMAND>:

One of these, defaults to help:

Command	Description
list-releases	Prints all releases for the given repo.
create-release	Creates a new release. It is recommended to use the web page, but this will work in case you need it.
upload-release	Uploads one-or-more files to an existing release, identified by it's tag name.
help	prints the help text (the usage summary above).

Configuration

Instead of specifying everything on the command line every single run, some TOML files can be used to persist project settings.

Exporting some environment variables would be similar, but that would be more annoying when working on multiple projects. One would have to constantly re-export the settings or use two shells. But then there's the issue of losing track of which shell has which settings.

Settings are retrieved from a table named the same as the project's path on disk. For example, gt_tool itself could have an entry as follows:

["/home/robert/projects/gt-tool"]
gitea_url = "https://demo.gitea.com/"
owner = "dummy"
repo = "gt-tool"
token = "fake-token"

Some may apply to all projects. For this, one can use the special [all] table.

[all]
gitea_url = "https://demo.gitea.com/"

Since the more-specific settings are preferred, these can be combined to have an override effect.

[all]
gitea_url = "https://demo.gitea.com/"
owner = "robert"
# no `repo = ` section because that must be project specific.
token = "fake-token"

# Override Gitea target so I can test my uploads privately.
["/home/robert/projects/gt-tool"]
gitea_url = "http://localhost:3000"
repo = "gt-tool"

Similar to how unspecified project settings will fall back to those in the "[all]" table, whole files will fall back to other, lower priority files. First, each dir in $XDG_CONFIG_DIRS is scanned for a gt-tool.toml file. Then, /etc/gt-tool.toml.

All config files MUST be named named gt-tool.toml.

Recognized Keys

Key	Description
gitea_url	URL of the Gitea server. Same as -u, --url, and $GTTOOL_GITEA_URL.
owner	Owner of the repository (individual, or organization). Combined with "repo" key to produce the fully-qualified-repo-name. Front-half of -r, --repo, and $GTTOOL_FQRN
repo	Name of the repository on the Gitea server. Combined with "owner" key to produce the fully-qualified-repo-name. Back-half of -r, --repo, and $GTTOOL_FQRN
token	Gitea auth token, exactly the same as $RELEASE_KEY_GITEA

Additional keys are quietly ignored. The config loading is done by querying a HashMap, so anything not touched doesn't get inspected. The only requirements are that the file is valid TOML, and that these keys are all strings.h