Forgejo curl helper
Go to file
earl-warren 908eab8b84
/ test (1.19) (push) Successful in 45s Details
/ test (1.20) (push) Successful in 44s Details
Merge pull request 'display information when login does nothing' (#2) from wip-log into main
Reviewed-on: #2
2023-09-10 09:49:30 +00:00
.forgejo/workflows create repository fixture 2023-09-03 00:45:40 +02:00
.gitignore initial 2023-09-02 23:22:12 +02:00
LICENSE add LICENSE 2023-09-03 15:57:13 +02:00 introduction to forgejo-curl 2023-09-03 14:09:46 +02:00 usage changed 2023-09-03 14:13:16 +02:00 display information when login does nothing 2023-09-10 11:25:29 +02:00

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:

$ --token ABC login
$ api

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:

$ --user joe --password passw0rd login
$ web --form avatar=@avatar.png


curl -sS -o /usr/local/bin/ && chmod +x /usr/local/bin/


$ --help - thin curl wrapper that helps with Forgejo authentication


  --verbose  display curl commands
  --debug    equivalent to set -x


  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. [--verbose] [--debug]
		  [--user <user>] [--password <password>]
		  [--scopes <scopes>] [--token <token>] login URL logout


    --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 --token ABCD \

      web           is not authenticated
      api, api_json use ABCD to authenticate --user joe --password passw0rd \

      web           is authenticated
      api, api_json use a newly generated token that belongs to user joe
		    with scope ["all"] to authenticate --user joe --password passw0rd --scopes '["write:package","write:issue"]' \

      web           is authenticated
      api, api_json use a newly generated token with write permission to packages and issues
		    to authenticate [--verbose] [--debug] web [curl options]"

  call curl using the CSRF token generated by the login command

  EXAMPLES web --form avatar=@avatar.png

      upload the file avatar.png and update the avatar of the logged in user [--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 api_json --data-raw '{"title":"TITLE"}' \

      create a new issue in the repository test api --form name=image.png --form attachment=@image.png \

      add the image.png file as an attachment to the issue 1234 in the test repository --help - display help --version - show the version


Local debug

The repositories are checked out in the same directory:

Install dependencies

The dependencies are installed manually or with:


Launch Forgejo

A Forgejo instance is launched with:

cd setup-forgejo
docker rm -f forgejo
./ setup
firefox http://$(cat forgejo-ip):3000

The user is root with password admin1234.

Run the tests

cd forgejo-curl
./ root admin1234 $(cat ../setup-forgejo/forgejo-token) $(cat ../setup-forgejo/forgejo-ip):3000