Git form saver#

What is Git form saver #

Git form saver is an HTTP API that pushes HTML forms to git repositories.

In a nutshell, API does the following:

Accept HTTP POST request.
Clone git repository passed in repo parameter.
Format the passed form fields using chosen formatter.
Append formatted data to a file passed in file parameter.
Push changes back to git repository.

When to use Git form saver #

Git form saver is useful when you want to allow appending data to specific file in a git repo through HTML form submission.

Use-cases

In public environment:
- Collect anonymous comments.
- Publish comments on statically-generated websites.
- A replacement for a database for simple data models.
In protected environment:
- Collect usage statistics from internal commandline tools.
- Simple plain-text file journaling without git access (mobile).

Security features #

Git form saver supports limiting user actions in 3 ways:

Git form saver uses SSH with private key authentication for all interactions with git repositories. It can only access repositories that allowed its public key.
Mandatory token — Git form saver appends form submissions only to the files, that contain a cryptographically secure Java Web Token (JWT) at the beginning of the file.
For protected environments, form owner can optionally set up secret value, required for the token verification.

Each git form saver instance can have a unique private key used for all git interactions. The same private key is used for generating the JWT. Private key never leaves the server and is hidden from target git repository and form owners.

Note

On GitHub, you can either add Git form saver’s public SSH key to your account, or create a separate GitHub account and add as a collaborator to your repo.

Mandatory token #

To enable Git form saver to append forms to a file, you need to generate a security token, and save it in the target file. Security token encodes repository URL and file path (with optional secret) using Git form saver’s private key. Long unique token ensures, that Git form saver can access only specific files inside the repository.

The token is different for each repository and for each file inside the repository.

Secret #

For protected environments, as internal networks, or mobile applications, security token can include additional secret value. Only form submissions, that include this secret value will be permitted.

Demo server #

To allow demo instance to access your repository, you need to add its SSH public key to the target git repository.

If your repository is on GitHub, you can just add a special GitHub account <https://github.com/git-form-saver> as collaborator.

Otherwise, add this public key to your repo for read and write access:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDAgnNh5XUOJItYkNrO0bSl0tNrOmbBNpD0Nl7Wo5JdoHEBZ9ksQIqdCiLwsqp/jdr9YCUiDKfMv6i3NCrFoYcD2u1x4p7bepKJ2bMaQRiDbzBGgI102lPjNSmiv7HxPDFdrJYtagWZGn0CCvVyK5jW1QV2w9CzQDJXlRI78DmhQnSJkVsE0cGNDvHXcWRi17MBAbcfx1+UOejHQsfP3NEVhS3QnPImS6cYk5hg+OO/ABnRsvCJCqoKpjvtQNSqLiYCZDuiOW7xvkC9zUw4ixAOjcuZvvqWYzFRypJSVscqCTW0aYWk5wadWw6lIbJP44zwp3cCtZ0qz9XZ9IYtLDarYpGERLQPplYBW+F6A7tirLx8OpALKDsXE4q5evgBWJofuWpfBl1tmkp2qySGnrmGsJYY6jFhGruvqGnZZzawU+NN51UBEP23sgZF7dozslgBR8D8fJJqhe/NEt1wtmXYfUYDJJg4KaqIER9sgSJKYwHhB2v37oby1n/j0S6Ti2M= gitformsaver@instance-1

Security token generation #

Use this form to generate a security token for your repo:

The token must be manually saved to the target file somewhere in the beginning (first 2 KiB).

Save text to any file #

Once the preparations are done, you can submit this form. The text will be appended to the target file, after a little delay.