Join a Ministry of Justice GitHub Organisation

WARNING: ⚠️ This repository is archived. The join-github application is no longer in use. We now recommend using GitHub's SSO links to join our organisations: Ministry of Justice SSO and MOJ Analytical Services SSO.

1. Prerequisites
2. Development
3. Deployment

Overview

Welcome to the GitHub repository for our "Join GitHub" onboarding application. This application streamlines the process of adding new users to our two primary GitHub organisations: ministryofjustice and moj-analytical-services.

The aim of this application is to provide a user-friendly interface for onboarding new team members into our GitHub organisations. It simplifies the administrative process, ensuring a smooth and efficient integration for new users.

Prerequisites

To develop, deploy or run this app, you will need to install the following:

• Python 3.11
• Docker
• Kubectl
• Helm

Development

Environment setup

Refer to the .env.example file for the required variables. Create a .env file from this in the project root. Note that .env is included in .gitignore so it is not tracked.

cp .env.example .env

To enable the auth0 authentication to run locally requires the actual AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET (by default set to dev). To access these login to auth0 and go to the operations-engineering tenant then,

Applications -> Applications -> ops-eng-test-azure-ad

Copy the Client ID and the Client Secret into your .env. Then source the .env and proceed.

source .env

Run application from Terminal

To run the application locally from the terminal use:

make local

Then open a browser to http://127.0.0.1:4567.

To use Docker run the following command and open a browser to http://0.0.0.0:4567:

make docker-up

Linting

To run the linter, run the following command:

make lint

Our project employs MegaLinter in our GitHub Actions to automatically ensure code quality on every pull request. It performs extensive linting across various languages and file formats, including Python, Bash, Markdown, Dockerfiles, JSON, Kubernetes configurations, and YAML. Configured in the .github/workflows/ directory, MegaLinter helps identify issues early, enforcing best practices and style guidelines.

Testing

To run the tests, run the following command:

make test

Deployment

Tokens and Secrets

All necessary tokens and secrets required for the deployment processes are manually set in the GitHub repository secrets. These include access tokens for various services and sensitive configuration data.

Deployment Pipelines

This project utilises two separate deployment pipelines:

Development Deployment Pipeline

To deploy to the operations-engineering-join-github-dev namespace, use the following steps:

1. Ensure your changes are committed to the main branch through the relevant pull request process.
2. The pipeline will automatically deploy the latest commit SHA to the development namespace using the Helm chart located in helm/join-github.

Production Deployment Pipeline

To deploy the latest tag push to GitHub in the production environment, follow these steps:

1. Clone the repository and ensure you have the latest updates from the main branch.

2. Create a new tag using the Git tagging system. For example, to create tag v0.0.1, run:

   git tag v0.0.1

When creating a new tag, use semantic versioning (e.g., v1.0.0, v1.0.1). This practice helps in maintaining version control and understanding the nature of the changes (major, minor, or patch).

3. Push the tag to the repository:

   git push --tags

4. The pipeline will automatically deploy the application to the operations-engineering-join-github-prod namespace.

Development environment

The Cloud Platform namespace for this project is called operations-engineering-join-github-dev.

You can see the development app running at: https://dev.join-github.service.justice.gov.uk/

And access Cloud Platform's namespace using:

kubectl get pods -n operations-engineering-join-github-dev

If you need to enable sending requests to GitHub (i.e. to add users to an MoJ GitHub organisation), you will need to enable the environment variable SEND_EMAIL_INVITES in the namespace. This is disabled by default.

kubectl -n operations-engineering-join-github-dev set env deploy/join-github SEND_EMAIL_INVITES=true

Production environment

The Cloud Platform namespace for the production environment is operations-engineering-join-github-prod.

You can see the production app running at: https://join-github.service.justice.gov.uk/

To interact with the production environment, use kubectl commands. For example:

kubectl get pods -n operations-engineering-join-github-prod

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you want to change.

Please make sure to update tests as appropriate.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact Us

If you have any questions or need further clarification, feel free to ask in the #ask-operations-engineering channel on Slack or email us at operations-engineering@digital.justice.gov.uk.