forgejo-curl.sh - a thin curl wrapper

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