Skip to content

Commit 5ad81d9

Browse files
ajay-dhangarajay-dhangar
committed
added docs for github actions doc
1 parent dbe7625 commit 5ad81d9

File tree

6 files changed

+625
-0
lines changed

6 files changed

+625
-0
lines changed

‎absolute-beginners/devops-beginner/github-actions/_category_.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"label": "GitHub Actions",
3+
"position": 10,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "GitHub Actions Automation",
7+
"description": "Learn to automate your build, test, and deployment pipeline. Master CI/CD to ensure CodeHarborHub projects are always production-ready. Discover how to create workflows, manage secrets, and integrate with other tools to streamline your development process."
8+
},
9+
"customProps": {
10+
"icon": "🚀",
11+
"status": "Essential"
12+
}
13+
}

‎absolute-beginners/devops-beginner/github-actions/ci-cd-for-mern.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: "CI/CD for MERN Stack"
3+
sidebar_label: "4. MERN Automation"
4+
sidebar_position: 4
5+
description: "Learn how to automate testing and building for MongoDB, Express, React, and Node.js applications. This guide walks you through creating a GitHub Actions workflow that handles both the frontend and backend of your MERN stack project, ensuring your code is always production-ready with every push to GitHub."
6+
tags: ["GitHub Actions", "CI/CD", "Automation", "DevOps", "CodeHarborHub", "MERN stack"]
7+
keywords: ["GitHub Actions", "CI/CD", "Continuous Integration", "Continuous Delivery", "Automation", "DevOps", "CodeHarborHub", "MERN stack", "MongoDB", "Express", "React", "Node.js"]
8+
---
9+
10+
Building a **MERN (MongoDB, Express, React, Node.js)** application is one thing; ensuring it works perfectly every time you update it is another. In a professional environment like **CodeHarborHub**, we use GitHub Actions to automate the testing and building of both the **Frontend** and the **Backend**.
11+
12+
:::info Why Automate MERN?
13+
MERN projects have multiple moving parts. You want to make sure that your React frontend doesn't break when you update your Node.js backend, and vice versa. Automation ensures that every change is tested and built correctly before it reaches production.
14+
:::
15+
16+
## The MERN Pipeline Strategy
17+
18+
In a MERN project, your repository usually has two main folders: `frontend/` and `backend/`. Our automation needs to handle both.
19+
20+
**Typically, a MERN CI/CD pipeline will have three main stages:**
21+
22+
1. **Dependency Install:** Download `node_modules` for both React and Node.js.
23+
2. **Lint & Test:** Check for syntax errors and run Unit Tests (using Jest or Mocha).
24+
3. **Build:** Create the production-ready "dist" or "build" folder for the frontend.
25+
26+
27+
## Creating the MERN Workflow
28+
29+
Create a file named `.github/workflows/mern-ci.yml`. This workflow uses **Jobs** to keep the backend and frontend tasks organized.
30+
31+
```yaml title="mern-ci.yml"
32+
name: MERN Stack CI
33+
34+
on:
35+
push:
36+
branches: [ main ]
37+
pull_request:
38+
branches: [ main ]
39+
40+
jobs:
41+
# JOB 1: Backend Testing
42+
backend-tests:
43+
runs-on: ubuntu-latest
44+
defaults:
45+
run:
46+
working-directory: ./backend # Tell GitHub to run commands inside 'backend' folder
47+
steps:
48+
- uses: actions/checkout@v4
49+
- name: Setup Node.js
50+
uses: actions/setup-node@v4
51+
with:
52+
node-version: '20'
53+
cache: 'npm' # Speeds up future builds!
54+
55+
- run: npm install
56+
- run: npm test
57+
58+
# JOB 2: Frontend Build
59+
frontend-build:
60+
runs-on: ubuntu-latest
61+
defaults:
62+
run:
63+
working-directory: ./frontend
64+
steps:
65+
- uses: actions/checkout@v4
66+
- name: Setup Node.js
67+
uses: actions/setup-node@v4
68+
with:
69+
node-version: '20'
70+
cache: 'npm'
71+
72+
- run: npm install
73+
- run: npm run build
74+
```
75+
76+
## Parallel vs. Sequential Execution
77+
78+
By default, GitHub Actions runs `backend-tests` and `frontend-build` at the **same time** (Parallel). This is the "Industrial Standard" because it saves time.
79+
80+
```mermaid
81+
graph LR
82+
A[Push Code] --> B[Job: Backend Tests]
83+
A --> C[Job: Frontend Build]
84+
B --> D{All Pass?}
85+
C --> D
86+
D -->|Yes| E[Deploy to Production]
87+
D -->|No| F[Stop & Notify Developer]
88+
```
89+
90+
## Handling Environment Variables (.env)
91+
92+
In your local MERN app, you use a `.env` file for your `MONGODB_URI`. **Never** commit that file to GitHub!
93+
94+
Instead, for your CI/CD tests, you can provide "dummy" variables directly in the YAML:
95+
96+
```yaml title="mern-ci.yml"
97+
- name: Run Backend Tests
98+
run: npm test
99+
env:
100+
MONGODB_URI: mongodb://localhost:27017/test-db
101+
JWT_SECRET: codeharborhub_secret_key
102+
```
103+
104+
## Performance Tip: Caching
105+
106+
MERN projects have massive `node_modules` folders. Without caching, your workflow might take 5 minutes. With caching, it can drop to 1 minute\!
107+
108+
Notice the `cache: 'npm'` line in our workflow above? That tells GitHub:
109+
*"If the `package-lock.json` hasn't changed, reuse the modules from the last time we ran this."*
110+
111+
## Professional "MERN" Rules
112+
113+
| Rule | Why? |
114+
| :--- | :--- |
115+
| **Separate Folders** | Use `working-directory` so your frontend tests don't try to run in the backend folder. |
116+
| **Node Versioning** | Always match the Node version in your workflow to your local development version. |
117+
| **Status Badges** | Add a "Build Passing" badge to your `README.md` to show off your professional automation! |
118+
119+
120+
:::info Industrial Level Bonus: Deployment
121+
Once your tests and builds are successful, you can add a third job to deploy your MERN app automatically. For example, you can deploy the backend to **AWS EC2** and the frontend to **Vercel** or **Netlify** with just a few extra steps in your workflow.
122+
123+
If you are using **Docker** for your MERN app, your GitHub Action can also build a **Docker Image** and push it to **Docker Hub** automatically after the tests pass. This is how real-world MERN applications are deployed at scale!
124+
:::

‎absolute-beginners/devops-beginner/github-actions/creating-first-workflow.mdx‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: "Creating Your First Workflow"
3+
sidebar_label: "3. First Workflow"
4+
sidebar_position: 3
5+
description: "Step-by-step guide to building your first automated pipeline with GitHub Actions. Learn how to set up a simple workflow that runs tests and checks your code environment every time you push to GitHub. Perfect for absolute beginners looking to get hands-on experience with CI/CD automation in their CodeHarborHub projects."
6+
tags: ["GitHub Actions", "CI/CD", "Automation", "DevOps", "CodeHarborHub"]
7+
keywords: ["GitHub Actions", "CI/CD", "Continuous Integration", "Automation", "DevOps", "CodeHarborHub", "MERN stack"]
8+
---
9+
10+
Welcome to the hands-on part of the **CodeHarborHub** DevOps track! If you've ever felt the stress of "I hope I didn't break anything" before pushing code, this lesson is for you.
11+
12+
We are going to build a **CI (Continuous Integration)** workflow that automatically greets you and checks your code environment every time you push to GitHub.
13+
14+
:::info Why This Workflow?
15+
This is a simple, beginner-friendly workflow that demonstrates the core concepts of GitHub Actions. It will help you understand how to structure your YAML files, use pre-built actions, and run shell commands in an automated environment. Plus, it's a fun way to see automation in action!
16+
:::
17+
18+
## The "Chef" Analogy
19+
20+
Think of a GitHub Action Workflow like a **Cooking Recipe**:
21+
22+
| Technical Term | Recipe Equivalent | What it does |
23+
| :--- | :--- | :--- |
24+
| **Event** | Someone orders food | The trigger that starts the process. |
25+
| **Runner** | The Kitchen | The environment where the work happens. |
26+
| **Job** | The Chef | A specific worker assigned to a task. |
27+
| **Step** | A Recipe Instruction | A single action (e.g., "Boil water"). |
28+
| **Action** | A Pre-made Sauce | A reusable component that performs a common task (e.g., "Use pre-made tomato sauce"). |
29+
30+
## Step 1: Preparing the Kitchen
31+
32+
GitHub looks for workflows in a very specific folder. If you don't put them here, they won't run!
33+
34+
1. Open your project in VS Code.
35+
2. Create a folder named `.github` (don't forget the dot!).
36+
3. Inside `.github`, create another folder named `workflows`.
37+
4. Inside `workflows`, create a file named `hello-world.yml`.
38+
39+
## Step 2: Writing the YAML Code
40+
41+
Copy and paste this code into your `hello-world.yml` file. Don't worry—we will break down exactly what each line does below.
42+
43+
```yaml title="hello-world.yml"
44+
# The name of your automation
45+
name: CodeHarborHub First Automation
46+
47+
# When should this run? (The Trigger)
48+
on: [push]
49+
50+
# What should it actually do?
51+
jobs:
52+
say-hello:
53+
# Use a fresh Ubuntu Linux server provided by GitHub
54+
runs-on: ubuntu-latest
55+
56+
steps:
57+
# Step 1: Download the code from your repo onto the runner
58+
- name: Checkout Repository
59+
uses: actions/checkout@v4
60+
61+
# Step 2: Run a simple terminal command
62+
- name: Greet the Developer
63+
run: echo "Hello CodeHarborHub Learner! Your automation is working! 🚀"
64+
65+
# Step 3: Check the environment version
66+
- name: Check Node Version
67+
run: node -v
68+
```
69+
70+
## Step 3: Understanding the "Why"
71+
72+
Let's look at the "Industrial Level" logic behind these lines:
73+
74+
### The `on: [push]` Trigger
75+
76+
This tells GitHub: "The moment someone pushes code to *any* branch, start this engine." In professional settings, we often change this to `on: [pull_request]` so we only run tests when someone wants to merge code.
77+
78+
### The `uses: actions/checkout@v4`
79+
80+
This is a **Pre-built Action**. Imagine you are a chef, and instead of farming the wheat yourself, you just buy flour. This action "buys the flour" by automatically cloning your code into the virtual machine so the next steps can use it.
81+
82+
### The `run:` command
83+
84+
This is exactly like typing a command into your computer's Terminal or Command Prompt. Anything you can do in a terminal, you can do here! In a real-world scenario, this is where you would run your tests (`npm test`), build your app (`npm run build`), or deploy to a server.
85+
86+
## Visualizing the Execution
87+
88+
Once you push this file to GitHub, here is what happens behind the scenes:
89+
90+
```mermaid
91+
sequenceDiagram
92+
participant U as You (Git Push)
93+
participant G as GitHub Registry
94+
participant R as Ubuntu Runner (The VM)
95+
96+
U->>G: Push .github/workflows/hello-world.yml
97+
G->>R: Spin up fresh Ubuntu VM
98+
R->>R: Step 1: Checkout Code
99+
R->>R: Step 2: Echo "Hello..."
100+
R->>R: Step 3: node -v
101+
R-->>G: Report "Success" (Green Checkmark ✅)
102+
```
103+
104+
## Step 4: Seeing it in Action
105+
106+
1. **Commit and Push:** Run `git add .`, `git commit -m "Add first workflow"`, and `git push`.
107+
2. **Go to GitHub:** Open your repository in your browser.
108+
3. **Click the "Actions" Tab:** You will see a yellow circle (running) or a green checkmark (finished).
109+
4. **Click the Workflow:** Click on "CodeHarborHub First Automation" to see the logs. You can expand each step to see the output!
110+
111+
## Common Mistakes for Beginners
112+
113+
* **Indentation Matters:** YAML is very picky. If your `steps:` is not indented correctly under `jobs:`, the workflow will fail. Always use **spaces**, never tabs.
114+
* **Typing the Folder Name:** Ensure it is `.github/workflows`. If you name it `.github/workflow` (singular), it will not work.
115+
* **Case Sensitivity:** `on: push` is different from `On: Push`. Always use lowercase for keywords.
116+
117+
:::tip Tip for Absolute Beginners
118+
Don't worry if it doesn't work the first time! Check the logs in the "Actions" tab to see what went wrong. The error messages are usually very descriptive and will guide you to the fix. This is how professional developers debug their CI/CD pipelines!
119+
120+
In the industrial world, we use these logs to debug **MERN** applications. If your frontend build fails, the logs here will tell you exactly which line of code caused the error! It's like having a detective's magnifying glass to find the culprit in your code.
121+
:::

‎absolute-beginners/devops-beginner/github-actions/github-actions-concepts.mdx‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "GitHub Actions Core Concepts"
3+
sidebar_label: "2. Core Concepts"
4+
sidebar_position: 2
5+
description: "Understand the fundamental building blocks of GitHub Actions automation, from Workflows to Runners. Learn how to structure your CI/CD pipelines effectively and follow best practices to ensure your CodeHarborHub projects are always production-ready."
6+
tags: ["GitHub Actions", "CI/CD", "Automation", "DevOps", "CodeHarborHub"]
7+
keywords: ["GitHub Actions", "CI/CD", "Continuous Integration", "Continuous Delivery", "Automation", "DevOps", "CodeHarborHub"]
8+
---
9+
10+
To build professional automation at **CodeHarborHub**, you need to speak the language of GitHub Actions. It isn't just about "running scripts"; it's about orchestrating a series of events across virtual environments.
11+
12+
## The Automation Anatomy
13+
14+
A GitHub Action is structured like a Russian Nesting Doll (Matryoshka). Each layer lives inside another.
15+
16+
```mermaid
17+
graph TD
18+
A[Event: Push/PR] --> B[Workflow: main.yml]
19+
subgraph "Inside the Workflow"
20+
B --> C[Job 1: Run Tests]
21+
B --> D[Job 2: Build & Deploy]
22+
C --> E[Step 1: Checkout Code]
23+
C --> F[Step 2: Setup Node.js]
24+
C --> G[Step 3: npm test]
25+
end
26+
```
27+
28+
In this example, the developer pushes code to a branch, which triggers the GitHub Actions workflow. The runner installs dependencies and runs tests. If the tests pass, it automatically deploys to production. If they fail, it notifies the developer to fix the code.
29+
30+
### 1. Workflow
31+
32+
The highest level of organization. A workflow is an automated process that you add to your repository. It is defined by a **YAML** file in your `.github/workflows` directory.
33+
* *Example:* `production-deploy.yml` or `unit-tests.yml`.
34+
35+
### 2. Events
36+
37+
An event is a specific activity in a repository that triggers a workflow run.
38+
* **Webhook events:** `push`, `pull_request`, `create` (new branch).
39+
* **Scheduled events:** `cron` (e.g., run backups every night at 12 AM).
40+
* **Manual events:** `workflow_dispatch` (a button you click to run the script).
41+
42+
### 3. Jobs
43+
44+
A job is a set of **steps** that execute on the same **runner**.
45+
* By default, multiple jobs in a workflow run in **parallel** (at the same time).
46+
* You can make jobs dependent on each other (e.g., Don't "Deploy" until "Test" is finished).
47+
48+
### 4. Steps
49+
50+
A step is an individual task. It can be a shell command (`run`) or an action (`uses`). All steps in a job run sequentially on the same runner.
51+
52+
### 5. Actions
53+
54+
An action is a standalone application that performs a complex but frequently repeated task. You "use" them to reduce the amount of code you write.
55+
* *Example:* `actions/checkout@v4` (Clones your code into the runner).
56+
57+
## How They Connect (The Logic Flow)
58+
59+
```mermaid
60+
graph TD
61+
A[Event: Push to Main] --> B{Workflow}
62+
63+
subgraph "Job: Build & Test (Runner: Ubuntu)"
64+
B --> J1[Step 1: Checkout Code]
65+
J1 --> J2[Step 2: Install Node.js]
66+
J2 --> J3[Step 3: Run npm test]
67+
end
68+
69+
subgraph "Job: Deploy (Runner: Ubuntu)"
70+
B --> D1[Step 1: Login to AWS]
71+
D1 --> D2[Step 2: Sync S3 Bucket]
72+
end
73+
74+
J3 -.->|Needs Success| D1
75+
```
76+
77+
## The Runner: Where the Magic Happens
78+
79+
A **Runner** is a server that has the GitHub Actions runner application installed. It listens for available jobs, runs the steps, and reports the progress back to GitHub.
80+
81+
<Tabs>
82+
<TabItem value="gh-hosted" label="GitHub-hosted Runners" default>
83+
84+
* **Managed by:** GitHub.
85+
* **OS:** Ubuntu Linux, Windows, or macOS.
86+
* **Clean Slate:** Every time a job runs, you get a fresh, clean virtual machine.
87+
* **Best For:** Most CodeHarborHub projects and standard MERN apps.
88+
89+
</TabItem>
90+
<TabItem value="self-hosted" label="Self-hosted Runners">
91+
92+
* **Managed by:** You (on your own server or EC2).
93+
* **Customization:** You can pre-install large dependencies to save time.
94+
* **Security:** Good for accessing private data centers.
95+
* **Best For:** Large-scale industrial apps with specific hardware needs.
96+
97+
</TabItem>
98+
99+
</Tabs>
100+
101+
## Understanding the YAML Syntax
102+
103+
A typical **CodeHarborHub** configuration looks like this. Notice the clear, indented structure:
104+
105+
```yaml title="ci-pipeline.yml"
106+
name: CI-Pipeline # 1. The Workflow Name
107+
on: [push] # 2. The Trigger (Event)
108+
109+
jobs: # 3. List of Jobs
110+
test-app: # Job ID
111+
runs-on: ubuntu-latest # 4. The Runner Environment
112+
113+
steps: # 5. List of Steps
114+
- name: Get Code
115+
uses: actions/checkout@v4
116+
117+
- name: Install dependencies
118+
run: npm install # 6. Standard Shell Command
119+
```
120+
121+
## Industrial Level Best Practices
122+
123+
| Concept | Professional Tip |
124+
| :--- | :--- |
125+
| **Timeouts** | Always set a `timeout-minutes` for your jobs so a stuck test doesn't waste your minutes. |
126+
| **Caching** | Use the `actions/cache` to remember your `node_modules`. This makes your builds 5x faster! |
127+
| **Matrix Strategy** | Use a `matrix` to test your app on Node 18, 20, and 22 simultaneously to ensure compatibility. |
128+
| **Secrets Management** | Store sensitive data (API keys, passwords) in GitHub Secrets and reference them in your workflow. |
129+
130+
:::info Did you know?
131+
You can also use **GitHub Environments** to set up different deployment targets (e.g., staging vs production) with specific secrets and approval rules. This adds an extra layer of control to your deployment process.
132+
133+
At **CodeHarborHub**, we recommend starting with a simple "Test" workflow. Once you see that green checkmark appearing on your Pull Requests, you'll never want to go back to manual testing!
134+
:::

0 commit comments

Comments
 (0)