This is a copy of the Github readme.
Find the original on https://github.com/bestia-dev/oauth2_cli_github_example

oauth2_cli_github_example

Example of GitHub api with Oauth2 CLI
version: 2025.310.1800 date: 2025-03-10 author: bestia.dev repository: GitHub

work-in-progress tutorial oauth2 cli

License oauth2_cli_github_example

Hashtags: #tutorial #oauth #rust #cli
My projects on GitHub are more like a tutorial than a finished product: bestia-dev tutorials.

Motivation

I want to use the GitHub api to automate the build and release workflow of my rust projects.
I used a personal secret token, but this is now short lived, cumbersome to generate and not recommended anymore.
Oauth2 is now recommended.

Github app

Github has the concept of GitHub app

In the settings of GitHub create a new GitHub App https://github.com/settings/apps.
App name: oauth2-cli-github-example
The name cannot contain underscore!
Homepage URL: https://bestia.dev/oauth2_cli_github_example/homepage.html
Callback URL: https://bestia.dev/oauth2_cli_github_example/callback.html

Enable device flow: this is mandatory for CLI applications

Repository permission Contents: read and write
Repository contents, commits, branches, downloads, releases, and merges.
Metadata mandatory: read only
Search repositories, list collaborators, and access repository metadata.

App ID: xxx
Using your App ID to get installation tokens? You can now use your Client ID instead.
Client ID: xxx

Device workflow with Oauth

There are many different workflows in Oauth2. That makes it so confusing.
For a CLI program it is recommended the device workflow. This must be enabled when creating the GitHub app.

I will save the tokens in a file encrypted with an SSH key.

For every app start check if the tokens are still valid and if needed use the refresh_token.
In case of any error start the "workflow to authentication with the browser".

Check if the file with encrypted tokens is present
  Decrypt the tokens
  Check if the access_token is still valid
    store access_token in global variable for use
  Else check if the refresh_token is valid
    Send the request to obtain new tokens
    Save the tokens encrypted with an SSH key
    store access_token in global variable for use

Workflow to authentication with the browser for device flow:

In the CLI program send a request to GitHub with client_id
Get a response with  device_code and user_code
Open a browser on GitHub, authenticate and type the user_code
GitHub will prepare the tokens on the server
Return to the CLI program and send a request to GitHub with  client_id and device_code
Get a response with access_token and refresh_token
Save the tokens encrypted with an SSH key

Open-source and free as a beer

My open-source projects are free as a beer (MIT license).
I just love programming.
But I need also to drink. If you find my projects and tutorials helpful, please buy me a beer by donating to my PayPal.
You know the price of a beer in your local bar ;-)
So I can drink a free beer for your health :-)
Na zdravje! Alla salute! Prost! Nazdravlje! 🍻

//bestia.dev
//github.com/bestia-dev
//bestiadev.substack.com
//youtube.com/@bestia-dev-tutorials