Table of contents
Introduction
Working in a team is one of the most important soft skills in the tech industry. Some people may believe they do not need to collaborate because they can handle everything themselves or some are less interested when it comes to working in a team. What would my advice be? When you come across such people, run.
You might wonder why I am opening with this statement. This project was a joint effort that demonstrated the value of teamwork in addressing hard technical challenges.
I collaborated with other developers to bring this project to life, combining our diverse skills and knowledge to design a system that ensures efficient testing and review of every pull request in an isolated environment.
This article is for intermediate learners who are knowledgeable about deploying an app in a Docker container and are about to take their learning further by understanding how to deploy commits made by pull requests using Github Bots.
If you stumbled upon this article as a beginner who has yet to understand how to deploy applications in a Docker container, read one of my articles: Deploying a three-tier application in Docker containers
Collaborative Problem-Solving and Project Redirection
Initially, our project brief described a system in which a bot would use the GitHub Actions pipeline to publish pull requests into Docker containers.
Each pull request was intended to be containerized independently, with the bot providing deployment status updates, comments, and application preview links.
However, after several planning sessions, the project brief was changed. We were directed not to use GitHub Actions, prompting our team to reconsider our strategy.
In reaction to this development, we unanimously agreed to use Bash scripts as the cornerstone for our deployment process.
If you want to try out a similar approach, you might consider using GitHub Actions to deploy pull requests into Docker containers.
Although our project shifted to using Bash scripts, GitHub Actions remains a powerful tool for automating such deployments and can be an excellent choice for your workflow.
Repository Structure and Integration
For this project, utilize two distinct repositories:
Bot Repository: This repository is used to host the code used in developing and managing the GitHub bot. It provides the code and configurations required for the bot to interface with GitHub, handle pull request events, and carry out deployment operations.
This repository is also used to host the code used in creating an application that will display the logs.
Application Repository: This repository contains the application you intend to deploy, as well as its Dockerfile. It contains all of the application code, dependencies, and Docker configuration necessary to build and operate the application in a containerized environment.
The bot application communicates with the GitHub App in the application's Repository to deploy each pull request.
When a pull request is created, the bot starts the deployment process with the Dockerfile from the Application Repository.
This separation enables clear structure and administration of the bot's logic and the application's deployment.
Key Concepts
Before we delve into the process of carrying out this deployment, it's important to grasp the software and tools that would be used to carry out these tasks.
Github bots is an automated application or software that performs numerous GitHub operations such as issue management, pull requests, and repository creation.
These bots can be configured to respond to specific events or orders, improve workflow efficiency, enforce rules, and deliver real-time updates.
Webhooks are automated messages sent by apps when an event happens. They carry a message, or payload, and are routed to a certain URL, usually the user's server.
It enables one program to communicate with another automatically and in real time, allowing systems to be alerted to certain occurrences.
Pull Request (PR) is a feature in version control systems like GitHub, GitLab, and Bitbucket that allows developers to notify team members about changes they have made to a branch in a repository.
It is a request to merge these changes into another branch, typically the main or master branch.
Probot is one of the frameworks used to create GitHub Apps. It is used to automate and streamline workflows on GitHub.
It leverages the GitHub API to perform various automated tasks, such as managing issues, pull requests, and repositories.
GitHub Apps
To create a GitHub App carry out the following steps:
click on the profile icon at the top right of your GitHub account.
click on settings.
on the left side panel, click on the Developer setting
click on the button New GitHub App.
fill in the following input field:
GitHub App name
write a description
Homepage URL. This will be your ngrok or smee.io URL
Webhook URL
Secret
upload a logo we can use to identify the bot.
generate a private key.
grant read and write access to the following Repository Permissions
Pull Request.
Deployments.
subscribe to the following events:
Pull request.
Pull request review.
Pull request review comment.
Pull request review thread.
Deployment status
select where you want this app to be installed.
click on the button Create GitHub App
Note:
Copy and paste your App ID, webhook URL, and webhook secret into a notepad
Your private key has been downloaded to your computer.
To see your app:
click on settings
click on application
At this point, you should see the bot you created.
GitHub Bot Development
To create a GitHub bot, we need to make use of these tools:
Probot
Smee.io or Ngrok
GitHub Apps
Probot
To get started run the command:
npx create-probot-app my-first-app
It will prompt you with the following questions to help you generate a template you can edit to suit your needs
Need to install the following packages:
create-probot-app@5.1.0
Ok to proceed? (y)
? App name: github-bot
? Description of app: A github bot that will update on the status of the deployment of pull request in docker containers
? Author's full name: zenitugo
? Which template would you like to use? deploy-js => Creates a deployment on a pull request event
type y which stands for yes.
give your app a name.
give it a description.
type in the full name of the Author. In this case, your name.
select what you need the template for. For this project, the bot would be used to say the status of the deployment of a pull request.
Image of the template created
input code to handle different types of pull requests into the template.
Input code to configure the link of the logging server so it can output the link to view the deployment logs.
input code to generate comments and status updates.
run
npm startcopy the URL on your terminal and paste on your desired browser. You should see this website.
click on the button or use an existing GitHub App.
Fill in the input field with your App ID and Webhook Secret you used while creating the GitHub app.
upload the private key file you generated while creating your GitHub app.
click on the submit button.
Ngrok / Smee.io
GitHub uses the webhook URL to communicate events (such as push notifications and pull requests) to your Probot application.
When you create a GitHub app, you define a webhook URL to which GitHub will deliver event alerts. You can create this webhook using either Ngrok or Smee.io.
How to create a Webhook URL with Ngrok
go to the ngrok website.
create an account or sign in if you already have one.
install ngrok on your operating system with the command:
sudo snap install ngrokconfigure your terminal
ngrok config add-authtoken YOUR_AUTH_TOKENRun the command
ngrok http 3000. This would create a tunnel to port 3000, which is the default port for a node js application.
Note: You can get your authentication token from the app
How to create a Webhook URL with Smee.io
go to the smee.io website.
click on the button Start a new channel.
copy the Webhook URL in the Webhook Proxy URL field
Bash Script Functionality
Since this is a collaborative project, I’m unable to share a sample of the script directly. However, I can walk you through the process and development of our script to give you insight into how we approached and created it.
For this project, you will need two scripts, one for deployment and one to clean up the resources deployed into the server.
Deployment Script
The Bash script is designed to deploy each pull request into its own Docker container. It builds the Docker image, starts the container, and ensures that the environment is correctly set up to run the application.
The deployment scripts functionality includes:
Environment Setup: The script relies on several environment variables to function correctly. This includes setting variables for the:
IP address, username, and password of the server. It could also be an SSH key if you are privileged to have it.
branch name.
pull request
repository
Error Handling: The script includes mechanisms to handle errors during deployment. It logs any issues encountered and provides feedback on what went wrong, allowing for prompt troubleshooting and resolution.
Preview links: The deployment script was configured to output the IP address and port of the deployed application.
Cleanup Script
The cleanup script is designed to remove all container and docker images, directories cloned into the server, and deployment log that was generated during the deployment process.
Core Logic
Your deployment script should contain the following main logic :
Ability to execute Docker commands to create and start containers for each pull request.
Ability to find available ports and assign them to the docker containers.
Ability to ensure that any event during deployment is logged and reported.
Ability to provide real-time feedback such as a link to the deployed application.
Logs Application Creation
To simplify your workflow and increase accessibility, create a separate application for log retrieval and administration.
This application is intended to collect logs from your log files, giving you a consolidated and user-friendly interface for monitoring and analyzing deployment operations.
The major goal of developing this application is to eliminate the need to manually access the server to check log files. Centralizing log access would improve efficiency and make it easier for team members to monitor the deployment process.
Bot Actions and Outputs
Comments: Once the script is executed, the bot posts comments on the pull request detailing the deployment status. This feature keeps you informed about the progress and any issues encountered.
Status Updates: The bot provides real-time updates on the deployment process, including when the container is starting, and running, or if any problems occur. This visibility is crucial for tracking the state of each pull request.
Preview Links & Log application Link: After successfully deploying a pull request, the bot outputs the preview link to the application running in the Docker container and the log application link to view the event that occurred during the deployment process. This link is posted in the pull request comments, allowing reviewers to interact with the deployed version of the app.
Image of the bot's actions and output when a pull request was reopened
Image of the bot's action when a pull request was closed
Conclusion
The concepts and procedures described in this article represent my team's collaborative work and resourcefulness.
I hope that sharing our experiences will help others wanting to implement similar solutions.
Before you begin deploying, you must first read and comprehend this article. The deployment procedure is complex and requires meticulous attention to detail to achieve a successful deployment.
Taking the time to understand each stage will help you avoid potential mistakes and provide a more seamless deployment experience.