Sending patches with git and a USP email

Written by David Tadokoro

Written on March 24, 2026, last modified on March 25, 2026

This tutorial explains how to send patches via git send-email using a USP email account, which involves some extra steps. We will be using kworkflow (kw) to simplify setup and automatically resolve maintainers when dealing with kernel contributions. An important prerequisite of this tutorial is reading the “Sending patches by email with git” post.

Introduction

When contributing to projects that do not use workflows like GitHub’s Pull-Requests or GitLab’s Merge-Requests (some call those Web-based workflows), but rather workflows where you need to send contributions via email, using a tool like git send-email is very convenient, as it greatly simplifies the process of converting and sending your commits. For example, you do not need to worry about your email messages (that contain your code) being misformatted or even leaving your local repository to accomplish the task.

Nevertheless, no matter the tool you use, you need to deal with authentication issues that may vary widely depending on your email account and provider. In this case, we are focusing on USP email accounts, which are Gmail accounts with some particularities when used to send patches.

What is the problem with USP emails?

Usually, when using Gmail accounts, you need to set up an App Password to signal Google that you are allowing an external service that uses this password to (in our case) send email messages with git send-email. To set up an App Password, you must first enable 2-Step Verification, which is not possible for USP emails.

To cover cases where setting up an App Password is not an option, Google still provides Less Secure Apps to allow authentication with the usual Gmail account password, even though this method is said to be unsupported since January 2025. You can check your USP Google account settings for the Less Secure Apps configuration, enable it, and try to use it, but I can tell you that this won’t work (at least, I would be very surprised if it did). The motive behind it is a long and obscure one, but the TL;DR is that the USP systems suffered security attacks in the first semester of 2025, which resulted in the admins locking down some vulnerable features like Less Secure Apps (you can imagine why).

The alternative: OAuth 2.0

OAuth 2.0 is a widely used protocol for authentication. It “delegates” authentication of the third-party app (again, in our case, git send-email) to an authorisation server (Google itself) without ever needing to store or share sensitive passwords.

This post is not about OAuth, so feel free to consult the linked page for further information.

Through OAuth, we can finally overcome the problems with USP emails, though it requires some (hopefully) not-so-complicated setup. More specifically, we need to use an email proxy that implements the OAuth protocol, which git send-email doesn’t do.

Summary of this tutorial

Running the email proxy
Configuring git send-email with kw send-patch
Testing the setup with kw send-patch

For students of the Free Software Development course, pay attention to these warning boxes, as they will contain specific instructions for this audience.

Running the email proxy

Our email proxy will be based on the email-oauth2-proxy project, a Python script configurable via an INI-like file. To avoid distro-specific nuances, we will use docker and docker-compose to streamline the process, so make sure they are installed and configured on your system!

Once you have docker and docker-compose installed and configured, clone this repository:

git clone https://github.com/davidbtadokoro/emailproxy-container.git

In this repo, you will find 3 files:

Dockerfile: the recipe for our cotainer image.
docker-compose.yaml: the orchestration script to simplify running our container.
emailproxy.config: the configuration file for the email proxy.

For this tutorial, you will only need to modify emailproxy.config; however, you can check and tinker with the other 2 files if you are curious, as they are really simple.

Opening emailproxy.config, you will notice some <FILL-HERE-...> fields:

...

[Account setup]

[<FILL-HERE-USP-EMAIL-ADDRESS>]
permission_url = https://accounts.google.com/o/oauth2/auth
token_url = https://oauth2.googleapis.com/token
oauth2_scope = https://mail.google.com/
redirect_uri = http://localhost
client_id = <FILL-HERE-CLIENT-ID>
client_secret = <FILL-HERE-CLIENT-SECRET>

...

You need to replace these fields with the USP email address you will use and the OAuth client ID and secret. These two client tokens need to be generated on your own, although you can reuse other “open” tokens.

For students of the Free Software Development course, consult the pad for the tokens and don’t forget to add your USP email address there as instructed by the mentors.

After filling the necessary fields, build and start the container with docker-compose:

docker compose up --build

If you investigated the Dockerfile, you may have noticed that this container does nothing (it only sleeps to infinity), so, on another terminal, enter the container:

docker exec -it emailproxy-container-server-1 /bin/bash

The container name should match the one above. If you run into any trouble, first check that you are using the correct name with docker ps. Inside the container, start the email proxy:

emailproxy --no-gui --external-auth --config-file /app/emailproxy.config

If everything worked correctly, you should see this at the end:

...
Initialised Email OAuth 2.0 Proxy - listening for authentication requests. Connect your email client to begin

Of course, don’t kill this process or the container, as the email proxy needs to be running for the next steps.

Configuring `git send-email` with `kw send-patch`

For this tutorial, we will not develop or submit a real contribution, so we will use the previously cloned repo for the email proxy in our git send-email configuration and testing. To accomplish this, we will leverage the convenience of kw send-patch.

We won’t cover installing kw, so refer to the kworkflow site or the GitHub repo if you need help.

On another terminal (again, keep the container and process running in the other terminals), go to the email proxy repo and run the following commands adapting the necessary fields:

kw send-patch --setup --name '<ADAPT-TO-YOUR-NAME-AND-SURNAME>'
kw send-patch --setup --email '<ADAPT-TO-YOUR-USP-EMAIL-ADDRESS>'
kw send-patch --setup --smtpuser '<ADAPT-TO-YOUR-USP-EMAIL-ADDRESS>'
kw send-patch --setup --smtpserver '127.0.0.1'
kw send-patch --setup --smtpserverport '2587'

These commands will modify your local Git configurations inside .git/config. In case of any trouble, check this file to see if the information is correct.

Testing the setup with `kw send-patch`

After starting the email proxy and configuring your git send-email with kw send-patch, we are ready to test our setup! Inside the email proxy repo, create any commit you wish and choose an email address(es) that will receive this test message.

For students of the Free Software Development course, create a commit titled <YOUR-FIRST-NAME> <YOUR-SURNAME> that adds a file named <YOUR-FIRST-NAME>.<YOUR-SURNAME>.txt that contains the string I am <YOUR-FIRST-NAME> <YOUR-SURNAME>. For the message recipients, use your own email address and dsl26oauthproxy@gmail.com.

After preparing our test commit, first let us check if kw send-patch would send the correct message to the correct people before actually sending the message (this is a good idea every time we are dealing with kw send-patch or git send-email) adapting the necessary fields:

kw send-patch --send --private --simulate --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

This command will open an editor with the contents of the message to be sent, including the code. With the --simulate flag, kw send-patch will do everything it would do if it were to send the message, except actually sending it. In this sense, you can check the output of the command to see if the To: and Cc: fields are correct, along with the message subject, contents, etc. After being sure that the correct message and recipients are generated, drop the --simulate flag and rerun the command:

kw send-patch --send --private --to='<EMAIL-ADDRESS-1>','<EMAIL-ADDRESS-2>' ...

After exiting the editor, you will be prompted to enter a password. For example:

...
Password for 'smtp://davidbtadokoro%40ime.usp.br@127.0.0.1:2587':

This password is not the same as the one you use for your account; actually, you can type in any password you wish, as this will be a local password for the email proxy. Just note that you need to use this same local password in future uses of the email proxy. After providing your password, go back to the terminal running the container (the one you ran docker exec), and note that you have an output similar to:

Please visit the following URL to authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br

Copy+paste or press [↵ Return] to visit the following URL and authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br then paste here the full post-authentication URL from the browser's address bar (it should start with http://localhost):

I suggest not using the [↵ Return] option and instead copying and pasting the URL into your browser. Doing so will open a Google authentication page that first asks whether you trust the client app associated with the tokens you provided, then prompts you to log in if necessary. After doing those, you will land on an Unable to connect or Problem loading page, which is expected! The only use of this page is its URL, starting with http://localhost/... that you need to copy and then paste back in the terminal running the container and press enter:

Copy+paste or press [↵ Return] to visit the following URL and authenticate account davidbtadokoro@ime.usp.br: https://accounts.google.com/o/oauth2/auth?client_id=17174063743-ts28k6ie7lmospgcfs775m8qvek6n4ma.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fmail.google.com%2F&response_type=code&access_type=offline&login_hint=davidbtadokoro%40ime.usp.br then paste here the full post-authentication URL from the browser's address bar (it should start with http://localhost): http://localhost/?iss=https://accounts.google.com&code=4/0Aci98E-fygcbbASm0JYllktwUvUo6gKexj4khWtKBMlLWWutANBX3tUtKHJAwaWq3uEcgg&scope=https://mail.google.com/

After that, you should see a log like:

SMTP (0.0.0.0:2587; davidbtadokoro@ime.usp.br) [ Successfully authenticated SMTP connection - releasing session ]

With that, you can go back to the terminal where you ran kw send-patch, and it should indicate success. Check the recipient(s) of your test email to see if the message(s) have arrived.

For students of the Free Software Development course, you don’t need to notify the mentors to check if the messages arrived in the previously provided email address, as just checking your own email inboxes will be sufficient.

Miscellaneous Notes

The email proxy approach used in this tutorial focused on portability and on the specific task of sending patches with kw/git. You can optimise the approach to run natively on your own system and for other purposes. For example, I use the email proxy project mentioned as a systemd service that initialises with my system and that I use for my email client.
We didn’t delve deep into the protocol part of sending emails, but this is related to SMTP. That is why you see that the server setup in emailproxy.config has only an SMTP section with very specific values.
As OAuth is a protocol, you could implement your own system to do this proxying. The question is that git send-email (and sometimes other email-related apps too) doesn’t implement the client-side of the protocol, so we need to fill this in some way or another.