Reviewed-on: #2 |
||
---|---|---|
.forgejo/workflows | ||
.gitignore | ||
LICENSE | ||
README.md | ||
forgejo-curl-test.sh | ||
forgejo-curl.sh |
README.md
forgejo-curl.sh
A thin curl wrapper that helps with Forgejo authentication. Beyond that it does not provide anything. It is low maintenance because it only relies on the authentication logic and does not need updating when the REST API (or the web UI endpoints) change.
The REST API endpoints can be used as documented. For instance:
$ forgejo-curl.sh --token ABC login https://forgejo.example.org
$ forgejo-curl.sh api https://forgejo.example.org/api/v1/user
{"id":1,"login":"root","login_name":"","..."starred_repos_count":0,"username":"root"}
The endpoints used by the Forgejo web UI can also be used, if given a user and a password to obtain a CSRF token. For instance:
$ forgejo-curl.sh --user joe --password passw0rd login https://forgejo.example.org
$ forgejo-curl.sh web --form avatar=@avatar.png https://forgejo.example.com/settings/avatar
Installation
curl -sS -o /usr/local/bin/forgejo-curl.sh https://code.forgejo.org/forgejo/forgejo-curl/raw/branch/main/forgejo-curl.sh && chmod +x /usr/local/bin/forgejo-curl.sh
Documentation
$ forgejo-curl.sh --help
forgejo-curl.sh - thin curl wrapper that helps with Forgejo authentication
COMMON OPTIONS
--verbose display curl commands
--debug equivalent to set -x
LOGIN AND TOKEN
The API endpoints that require authentication will be given the
token provided with the --token argument. If not provided, it will
be generated (and named forgejo-curl), using the --user and
--password credentials.
The web endpoints that require authentication will be given a cookie
and CSRF token created using the the --user and --password credentials
On a successful login the credentials are stored in the /home/earl-warren/.forgejo-curl
directory to be used by the web, api, api_json commands. The logout
command removes the /home/earl-warren/.forgejo-curl directory.
forgejo-curl.sh [--verbose] [--debug]
[--user <user>] [--password <password>]
[--scopes <scopes>] [--token <token>] login URL
forgejo-curl.sh logout
OPTIONS
--user <user> username
--password <password> password of <user>
--scopes <scopes> scopes of the token to be created (default ["all"])
--token <token> existing personal access token
EXAMPLES
forgejo-curl.sh --token ABCD \
login https://forgejo.example.com
web is not authenticated
api, api_json use ABCD to authenticate
forgejo-curl.sh --user joe --password passw0rd \
login https://forgejo.example.com
web is authenticated
api, api_json use a newly generated token that belongs to user joe
with scope ["all"] to authenticate
forgejo-curl.sh --user joe --password passw0rd --scopes '["write:package","write:issue"]' \
login https://forgejo.example.com
web is authenticated
api, api_json use a newly generated token with write permission to packages and issues
to authenticate
forgejo-curl.sh [--verbose] [--debug] web [curl options]"
call curl using the CSRF token generated by the login command
EXAMPLES
forgejo-curl.sh web --form avatar=@avatar.png https://forgejo.example.com/settings/avatar
upload the file avatar.png and update the avatar of the logged in user
forgejo-curl.sh [--verbose] [--debug] api|api_json [curl options]"
call curl using the token given to (or generated by) the login command. If called using
api_json, the Content-Type header is set to application/json.
EXAMPLES
forgejo-curl.sh api_json --data-raw '{"title":"TITLE"}' \
https://forgejo.example.com/api/v1/repos/joe/test/issues
create a new issue in the repository test
forgejo-curl.sh api --form name=image.png --form attachment=@image.png \
https://forgejo.example.com/api/v1/repos/joe/test/issues/1234/assets
add the image.png file as an attachment to the issue 1234 in the test repository
forgejo-curl.sh --help - display help
forgejo-curl.sh --version - show the version
Hacking
Local debug
The repositories are checked out in the same directory:
- forgejo-curl: forgejo-curl
- setup-forgejo: setup-forgejo
Install dependencies
The dependencies are installed manually or with:
setup-forgejo/forgejo-dependencies.sh
Launch Forgejo
A Forgejo instance is launched with:
cd setup-forgejo
docker rm -f forgejo
./forgejo.sh setup
firefox http://$(cat forgejo-ip):3000
The user is root
with password admin1234
.
Run the tests
cd forgejo-curl
./forgejo-curl-test.sh root admin1234 $(cat ../setup-forgejo/forgejo-token) $(cat ../setup-forgejo/forgejo-ip):3000