Robert Garrett
e7e8a2871b
I need some kind of automated testing, and Cargo has a test framework built-in. This isn't the smartest test and depends upon another test-less function. Building a mocking environment is possible but means I'm trying to emulate some behavior I don't fully understand -- that's why I need tests in the first place. That path leads to tests for my tests and that's stupid. Instead, I'm having the test read config from the environment and hit a real Gitea server. It's up to the user to ensure they have one.
65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# gt-tools
|
|
|
|
CLI tools for interacting with the Gitea API. Use interactively to talk to your Gitea instance, or automatically via a CI/CD pipeline.
|
|
|
|
## Usage
|
|
|
|
```txt
|
|
Usage: gt-tools --url <GITEA_URL> --repo <REPO> <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=]
|
|
-r, --repo <REPO> [env: GTTOOL_FQRN=]
|
|
-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](https://docs.gitea.com/development/oauth2-provider#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.
|
|
|
|
### `<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). |
|
|
|
|
## Unit Testing
|
|
|
|
The unit test~~s~~ require a Gitea server to execute against. This information is supplied by environment variables rather than on the command line, but it is otherwise exactly the same usage.
|
|
|
|
| Variable | Description |
|
|
|-|-|
|
|
| TEST_GITEA_SERVER | Server URL, match `-u`, `--url` |
|
|
| TEST_GITEA_REPO | Owner + repo name, match `-u` `--repo` |
|
|
| TEST_GITEA_KEY | API key, match `RELEASE_KEY_GITEA`. The use of a new variable for the API token is to help avoid accidentally touching a production environment during test execution. |
|
|
| TEST_GITEA_RELEASE_TAG | Git tag used to identify the Release. Same as `upload-release`'s positional argument `<TAG_NAME>`. |
|
|
|