How To Authorize a User Using the GitHub OAuth API , Python and Flask: Part One.

Overview and Development Environment setup.

In this three part series, I will take you through the steps needed to create an application that authenticates its users using the GitHub Auth API. Ever been to a site, then to use their services or access their content, you are asked to sign in or sign up. But rather than use your email, user name and password, they give the opportunity to sign in or sign up using Google or Facebook or Twitter. That is what I aim to show you, but in our case, our user will login in using GitHub.

Why would I need GitHub sign up for my application?. Well, I am developing an application that will automatically run tests on my users’ code hosted on GitHub and then provide them with both a dashboard showing them various stats about the status of their code, including failing and passing tests as well as code coverage. The application will use pytest and coverage initially but to run the tests on the users’ code, I need access to their GitHub account. Are you ready to create a GitHub authentication application? Let’s go.

In this part, we will set up the local development environment.In part two we will develop the application and deploy it locally and finally in part three we will deploy it to Heroku. Mind you, I follow strict development procedures, so you may get annoyed by some of my practices. So what are we going to do?

1. Create a GitHub repository using a template.
2. A look At the Project Layout
3. Creating the virtual environment
4. Creating the pre-commit hooks
5. Creating a feature development branch
6. Pushing the code to GitHub
7. Creating a pull request
8. Conclusion

1. Create a GitHub repository using a template.

We will use an existing repository template that has a nice project structure to get started. Navigate to the api-template repository and click on Use this template button

Give your project a good name, I called mine github-oauth-app (do not give yours the same name as I will use the same name on Heroku) then give it a good description. Now just clone the project and let’s work on it locally. The repository default branch in the development branch. You may have to adjust your main branch name to follow along. We will also create the other branches:

• staging branch for staging our application before merging them into the release and production branch.
• production branch will host the application code that will run in production i.e deployed to Heroku
• release branch will contain code for our latest release
• optionally a docs branch that will host the sphinx documentation for the application.

Our development workflow will be pretty simple:

• Create a feature branch for creating a new feature
• Create unit tests for the new feature
• Create the feature so that the unit tests pass
• Push the code to GitHub
• Create a pull request and merge to the development branch
• Merge the development branch into the staging branch and deploy the app to a staging environment
• Merge the staging environment into the release branch
• Merge the release branch into the production branch and then deploy the application to production.

2. A look at the project layout

That is the initial project layout;

• .github/workflows/development-workflow.yml will contain our workflows that we will use to automate the deployment of the finished application to Heroku.
• The API folder will contain our code and html templates
• The tests folder contain our application testing code
• The .gitignore contains files that we do not want committed to GitHub.
• header.png will contain the image that will appear on the Project description on GitHub.
• LICENSE tells anyone who has access to this project what they can use it for and what they cannot. It is MIT, so they can pretty much use it as they wish.
• The Makefile enables us to automate various tasks such as requirements installation, running code quality checkers and also running the application.
• manage.py is the script that we will use to automate the running of the application.
• The Procfile will contain instructions that will tell Heroku how to launch our application.
• pytest.ini contains instructions that guide pytest, our test runner, on how to run tests against our code.
• README.md describes our project and will appear on the project page on GitHub.
• requirements.txt contains the runtime requirements for this project wheres requirements-dev.txt contains the development dependencies.

3. Creating the virtual Environment

I promised to follow best practices in this project, so let us start by setting up git pre-commit hooks. Create a virtual environment to isolate our development environment from the rest of the python environments found locally:

python3 -m venv venv
source venv/bin/activate

Add the following to requirements-dev.txt:

setuptools==60.10.0
pre-commit-2.18.

Creating the Makefile

Add the following to the Makefile

The first command, update-pip, simply updates pip. The second command, install, installs the project requirements listed in requirements.txt, the third command, install-dev, installs the development requirements from requirements-dev.txt while run, simply starts the flask application. To install the project requirements, run:

make update-pip
make install-dev

4. Creating the Pre-commit hooks

To create the pre-commit hooks, first install pre-commit, then create the pre-commit config file:

pre-commit install
touch .pre-commit-config.yaml

Add the following to .pre-commit-config.yaml file:

The above pre-commit hooks enable us to run code quality checks on our code before committing them to GitHub. I will write a post on what each does, but for now, just use the hooks shown above. To use them, first add the following to our requirements-dev.txt file:

commitizen==2.24.0
pre-commit==2.18.1

Install these requirements:

make install-dev

To use the pre-commit hooks, run the following commands:

git tag -a v0.0.1 -m “Initial tag.”

This creates the very first tag for our project. The subsequent tags will be created by commitizen.

cz init

This command initializes commitizen, which will keep track of our versions for us and enforce conventional commit standards to our commits.

Choose pyproject.toml as your config file (just press Enter key at the prompt.)

Choose cz_conventional_commit for commit rule (again just press Enter key at the prompt.). Select v0.0.1 as the current tag.

For the version format accept use v”$version” as the version format.

5. Create a feature development branch

One of our pre-commit hooks prevents us from committing our code directly to the development, production or staging branches So to push our code to GitHub, we have to create a feature branch, then push our code to that branch. Then on GitHub, we will make a pull request to merge the changes to the development branch.

git checkout -b feature/project-layout

Then let us try out our pre-commit hooks:

pre-commit run

Your output should look like:

6. Pushing the code to GitHub

Now let us push our code to GitHub:

git add .
git commit -m “feat: created the project development setup.”
git push

Ensure that the commit message has the form “feat: your message” or commitizen will reject the commit. Read more about conventional commits. Pre-commit might reject the changes:

Repeat the procedure:

git add .
git commit -m “feat: created the project development setup.”
git push -u origin feature/project-layout

Finally push the tag that we created to GitHub:

git push origin v0.0.1

7. Creating the Pull Request

Navigate to your GitHub repository.

Select the Compare & pull request button to create a new pull request. Then select Create pull request in the resulting page:

And select Merge pull request

In the final screen select Confirm merge

The code in your development branch should be up-to date with that in the feature/project-layout branch. You should also have an initial tag of v0.0.1.

8. Conclusion

In this post we set out to set up a local development environment for an application that will use flask and GitHub OAuth API to register new users and authenticate registered users. We did the following:

• Used a template from a github repository to create the initial project layout
• Briefly examined the project layout
• Created a virtual environment and installed a couple of requirements for our application.
• Set up pre-commit hooks that will enforce code quality standards as well as commits for our project.
• Set up a feature development branch, pushed code to this branch then created a pull request to merge the feature development branch into the development branch.

In the next post, we will create the application and deploy it locally. The code for this application is here github-oauth-app. I am Lyle, a junior software engineer with a passion for developing, testing and deploying scalable services. You can find me on twitter, linkedin, github and here’s my portfolio. See you next time.