📄 GitHub CI/CD Template

Welcome to the GitHub CI/CD Template repository! This project provides a robust and flexible CI/CD pipeline setup using GitHub Actions, tailored for project using Python for backend, node frontend, docker-compose or Dockerfile. Leverage this template to automate your development workflow, from testing and building to deployment and monitoring.

📚 Table of Contents

• Features
• Getting Started
  • Prerequisites
  • Installation
  • Environment Setup
  • Pre-Commit Hooks
  • Extra Steps
• Usage
• Contributing
• License
• Contact

🌟 Features

• Automated Testing: Run tests automatically on each push and pull request.
• Continuous Deployment: Deploy your application seamlessly to your chosen platform.
• Code Quality Checks: Enforce coding standards with linting and formatting tools.
• Build Optimization: Optimize build processes for faster deployment cycles.
• Notifications: Receive updates and alerts on pipeline status via email or chat integrations.

🚀 Getting Started

📋 Prerequisites

Before you begin, ensure you have met the following requirements:

• GitHub Account: You need a GitHub account to use GitHub Actions.
• Python 3.12+: Ensure Python is installed on your local machine.
• Git: Install Git to clone the repository.
• NVM: (Optional) Node.js installation environment versions control
• Node.js 22.x+: (Optional) (Required to Push) Used as lint orchestration manager in pre-commit and pre-push

🔨 Installation

1. Clone the Repository

   git clone https://github.com/JuanVilla424/github-cicd-template.git

2. Navigate to the Project Directory

    cd github-cicd-template

🔧 Environment Setup

Mandatory: Setting Up a Python Virtual Environment

Setting up a Python virtual environment ensures that dependencies are managed effectively and do not interfere with other projects.

1. Create a Virtual Environment

   python -m venv venv

2. Activate the Virtual Environment

   On Unix or MacOS:

   source venv/bin/activate

   On Windows:

    .\venv\Scripts\activate

   • or

    powershell.exe -ExecutionPolicy Bypass -File .\venv\Scripts\Activate.ps1

3. Upgrade pip

   pip install --upgrade pip

4. Install Dependencies

   pip install -r requirements.txt
   pip install poetry
   poetry lock
   poetry install

   • Deactivate the Virtual Environment

   When you're done, deactivate the environment:

    deactivate

5. Docker Extra Steps: Install Scoop and then install hadolint using scoop, refer to Extra Steps

🛸 Pre-Commit Hooks

Install and check pre-commit hooks: MD files changes countermeasures, python format, python lint, yaml format, yaml lint, version control hook, changelog auto-generation

pre-commit install
pre-commit install -t pre-commit
pre-commit install -t pre-push
pre-commit autoupdate
pre-commit run --all-files

📌 Extra Steps

1. Docker:

   • Using MacOs or Linux:

     brew install hadolint

   • On Windows as non-admin user:

     Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
     Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
     scoop install halint

🛠️ Usage

To utilize the CI/CD pipeline, follow these steps:

1. Configure GitHub Actions

   • Navigate to the .github/workflows/ directory.
   • Customize the ci.yml file according to your project's requirements.
   • Customize the python.yml file to format and lint python code.
   • Customize the node.yml file to format and lint node.js code if you are hosting frontend.
   • Customize the release-controller file to add or remove [backend, frontend, docker deployment, database]

2. Set Up Secrets

   • Go to your GitHub repository settings.
   • Navigate to Secrets and add necessary secrets like CODECOV_KEY, etc.

3. Triggering the Pipeline

   • Push to Branches: Pushing code to dev, test, prod, or main branches will trigger the pipeline.
   • Pull Requests: Opening or updating pull requests will run tests and checks.

4. Monitoring Pipeline Status

   • Check the Actions tab in your GitHub repository to monitor the status of your workflows.
   • Integrate notifications with Slack, Email, or other communication tools for real-time updates.

🤝 Contributing

Contributions are welcome! To contribute to this repository, please follow these steps:

1. Fork the Repository

2. Create a Feature Branch

   git checkout -b feature/your-feature-name

3. Commit Your Changes

   git commit -m "feat(<scope>): your feature commit message - lower case"

4. Push to the Branch

   git push origin feature/your-feature-name

5. Open a Pull Request into dev branch

Please ensure your contributions adhere to the Code of Conduct and Contribution Guidelines.

🛠️ Adding a New Workflow

1. Create a New Workflow File

   touch .github/workflows/new-workflow.yml

2. Define the Workflow

   Customize the workflow according to your needs, using existing workflows as references.

3. Commit and Push

   git add .github/workflows/new-workflow.yml
   git commit -m "chore(core): added new workflow - lower case"
   git push origin feature/your-feature-name

📫 Contact

For any inquiries or support, please open an issue or contact [email protected].

---

📜 License

2024 - This project is licensed under the GNU General Public License v3.0. You are free to use, modify, and distribute this software under the terms of the GPL-3.0 license. For more details, please refer to the LICENSE file included in this repository.