Forgejo curl helper
Go to file
earl-warren 4120ec71f8
/ test (map[image:codeberg.org/forgejo-experimental/forgejo version:1.21.0-6-rc2]) (push) Successful in 59s Details
/ test (map[image:codeberg.org/forgejo/forgejo version:1.19]) (push) Successful in 1m6s Details
/ test (map[image:codeberg.org/forgejo/forgejo version:1.20]) (push) Successful in 1m4s Details
Merge pull request 'improve the title' (#5) from wip-cascade-setup-forgejo into main
Reviewed-on: #5
2023-11-03 23:41:19 +00:00
.forgejo cascade PR goes to a fork for setup-forgejo 2023-11-04 00:09:27 +01:00
.gitignore initial 2023-09-02 23:22:12 +02:00
LICENSE add LICENSE 2023-09-03 15:57:13 +02:00
README.md improve the title 2023-11-03 23:11:22 +00:00
forgejo-curl-test.sh support a token stored in a file 2023-09-24 17:27:19 +02:00
forgejo-curl.sh cosmetic change 2023-10-26 17:01:50 +02:00

README.md

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:

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