Part 1: Introduction to GitHub Actions and First Workflow

Introduction

I still remember the frustration of manually deploying my first TypeScript microservice. Every deployment involved:

1. SSH into the server

2. Pull the latest code

3. Run npm install

4. Run tests (and hope they pass)

5. Build the project

6. Restart the service

7. Check logs to ensure it's working

This process took 15-20 minutes and was error-prone. I once deployed broken code to production because I forgot to run tests locally. That's when I discovered GitHub Actions, and it transformed how I work. Now, every push triggers automated tests, builds, and deployments—all without my intervention.

In this part, I'll introduce you to GitHub Actions and help you create your first workflow for a TypeScript microservice.

What is GitHub Actions?

GitHub Actions is GitHub's built-in CI/CD (Continuous Integration/Continuous Deployment) platform. It allows you to automate workflows directly in your GitHub repository.

What Can You Automate?

From my experience, here's what I automate with GitHub Actions:

Development Workflows:

• Run tests on every push

• Lint code for style violations

• Type-check TypeScript

• Run security scans

Build and Package:

• Build TypeScript to JavaScript

• Create Docker images

• Publish npm packages

• Generate documentation

Deployment:

• Deploy to staging on merge to develop

• Deploy to production on release tags

• Database migrations

• Rollback on failure

Maintenance:

• Auto-update dependencies

• Close stale issues

• Label pull requests

• Generate release notes

Core Concepts

1. Workflows

A workflow is an automated process defined in a YAML file stored in .github/workflows/ in your repository.

Example: .github/workflows/ci.yml

name: CI Pipeline
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

2. Events

Events trigger workflows. Common events I use:

• push: Code is pushed to repository

• pull_request: PR is opened/updated

• release: New release is published

• schedule: Run on a schedule (cron)

• workflow_dispatch: Manual trigger

3. Jobs

A workflow contains one or more jobs that run in parallel (by default) or sequentially.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  
  build:
    runs-on: ubuntu-latest
    needs: test  # Runs after 'test' job
    steps:
      - run: npm run build

4. Steps

Steps are individual tasks within a job. They run sequentially.

steps:
  - name: Checkout code
    uses: actions/checkout@v3
  
  - name: Install dependencies
    run: npm install
  
  - name: Run tests
    run: npm test

5. Runners

Runners are servers that execute your workflows. GitHub provides:

• ubuntu-latest (most common for Node.js)

• windows-latest

• macos-latest

You can also use self-hosted runners.

6. Actions

Actions are reusable units of code. You can use actions from:

• GitHub Marketplace (actions/checkout@v3)

• Your own repository

• Other repositories

My First Workflow: A Real Example

When I started my TypeScript payment service, this was my first workflow:

Project Structure

payment-service/
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   ├── index.ts
│   ├── services/
│   └── controllers/
├── tests/
│   └── payment.test.ts
├── package.json
├── tsconfig.json
└── README.md

The First Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      # Step 1: Check out the code
      - name: Checkout code
        uses: actions/checkout@v3
      
      # Step 2: Set up Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      # Step 3: Install dependencies
      - name: Install dependencies
        run: npm ci
      
      # Step 4: Run linter
      - name: Lint code
        run: npm run lint
      
      # Step 5: Type check
      - name: Type check
        run: npm run type-check
      
      # Step 6: Run tests
      - name: Run tests
        run: npm test

What This Workflow Does

When I push code or open a PR:

1. Checks out my code using actions/checkout@v3

2. Sets up Node.js 18 using actions/setup-node@v3

3. Installs dependencies with npm ci (faster and more reliable than npm install)

4. Lints the code to catch style issues

5. Type checks to catch TypeScript errors

6. Runs tests to ensure functionality

If any step fails, the workflow stops and I get a notification.

Creating Your First Workflow

Let's create a workflow for a TypeScript microservice step by step.

Step 1: Prepare Your Project

package.json scripts:

{
  "name": "user-service",
  "version": "1.0.0",
  "scripts": {
    "dev": "ts-node-dev src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "jest",
    "test:coverage": "jest --coverage",
    "lint": "eslint src/**/*.ts",
    "lint:fix": "eslint src/**/*.ts --fix",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "eslint": "^8.0.0",
    "jest": "^29.0.0",
    "ts-jest": "^29.0.0",
    "ts-node-dev": "^2.0.0",
    "typescript": "^5.0.0"
  }
}

Step 2: Create Workflow Directory

mkdir -p .github/workflows

Step 3: Create Workflow File

touch .github/workflows/ci.yml

Step 4: Write the Workflow

# .github/workflows/ci.yml
name: CI

# Trigger on push to main/develop or on pull requests
on:
  push:
    branches:
      - main
      - develop
  pull_request:
    branches:
      - main
      - develop

jobs:
  # Job 1: Run tests and checks
  test:
    name: Test and Lint
    runs-on: ubuntu-latest
    
    steps:
      # Checkout the repository code
      - name: Checkout repository
        uses: actions/checkout@v3
      
      # Set up Node.js environment
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'  # Cache npm dependencies
      
      # Install dependencies
      - name: Install dependencies
        run: npm ci
      
      # Run ESLint
      - name: Run linter
        run: npm run lint
      
      # Run TypeScript type checking
      - name: Type check
        run: npm run type-check
      
      # Run Jest tests
      - name: Run tests
        run: npm run test:coverage
      
      # Upload coverage report (optional)
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/coverage-final.json
          flags: unittests
          name: codecov-umbrella

Step 5: Commit and Push

git add .github/workflows/ci.yml
git commit -m "ci: add GitHub Actions workflow"
git push origin main

Step 6: Watch It Run!

1. Go to your GitHub repository

2. Click on Actions tab

3. You'll see your workflow running

Understanding the Workflow Output

When the workflow runs, you'll see:

✓ Checkout repository (2s)
✓ Setup Node.js (3s)
✓ Install dependencies (15s)
✓ Run linter (4s)
✓ Type check (6s)
✓ Run tests (8s)

Total: 38s

If any step fails:

✓ Checkout repository (2s)
✓ Setup Node.js (3s)
✓ Install dependencies (15s)
✗ Run linter (2s)
  Error: ESLint found 3 errors
  
  src/services/payment.service.ts
    12:5  error  'amount' is defined but never used  @typescript-eslint/no-unused-vars

Real-World Example: My Payment Service Workflow

Here's the actual workflow I use for my payment processing microservice:

# .github/workflows/ci.yml
name: Payment Service CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

env:
  NODE_VERSION: '18'

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    
    # Service containers (PostgreSQL for integration tests)
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: payment_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run Prisma generate
        run: npx prisma generate
      
      - name: Run database migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/payment_test
      
      - name: Lint code
        run: npm run lint
      
      - name: Type check
        run: npm run type-check
      
      - name: Run unit tests
        run: npm run test:unit
      
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/payment_test
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_TEST_KEY }}
      
      - name: Generate coverage report
        run: npm run test:coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        if: always()
        with:
          files: ./coverage/lcov.info

What makes this workflow production-ready:

1. PostgreSQL service container for integration tests

2. Prisma migrations run before tests

3. Separate unit and integration tests

4. Secrets management for API keys

5. Coverage reporting with Codecov

6. Environment variables for configuration

Common Workflow Triggers

Push to Specific Branches

on:
  push:
    branches:
      - main
      - develop
      - 'feature/**'  # Any feature branch

Pull Request Events

on:
  pull_request:
    types:
      - opened
      - synchronize  # New commits pushed
      - reopened
    branches:
      - main

Scheduled Workflows (Cron)

on:
  schedule:
    # Run every day at 2 AM UTC
    - cron: '0 2 * * *'

I use this for:

• Dependency update checks

• Database backup jobs

• Cleanup old artifacts

Manual Triggers

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        type: choice
        options:
          - staging
          - production

Multiple Events

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:

Viewing Workflow Results

Success

When everything passes:

# In PR, you'll see:
✓ CI / Test (pull_request) — Successful in 1m 23s

# You can merge with confidence!

Failure

When something fails:

# In PR, you'll see:
✗ CI / Test (pull_request) — Failed in 45s

# Click "Details" to see what failed
# Fix the issue and push again

GitHub Status Checks

I configure branch protection to require:

Settings → Branches → Branch protection rules → main

☑ Require status checks to pass before merging
  - Test and Lint
  - Build

Now PRs can't be merged until workflows pass!

My Workflow Development Process

1. Start Simple

# First workflow - just run tests
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm test

2. Add Gradually

# Add linting
- run: npm run lint

# Add type checking
- run: npm run type-check

3. Optimize

# Add caching
- uses: actions/setup-node@v3
  with:
    cache: 'npm'

# Add services for integration tests
services:
  postgres:
    image: postgres:14

4. Refine

# Add better names and organization
- name: Run unit tests
  run: npm run test:unit

- name: Run integration tests
  run: npm run test:integration

Debugging Workflows

Enable Debug Logging

In your repository settings:

Settings → Secrets → Actions → New repository secret

Name: ACTIONS_STEP_DEBUG
Value: true

Then re-run the workflow to see detailed logs.

Common Issues I've Faced

Issue 1: Tests Pass Locally but Fail in CI

# Problem: Missing environment variables
# Solution: Add to workflow
env:
  NODE_ENV: test
  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test

Issue 2: Slow Workflow

# Problem: Re-installing dependencies every time
# Solution: Enable caching
- uses: actions/setup-node@v3
  with:
    cache: 'npm'

Issue 3: Integration Tests Fail

# Problem: PostgreSQL not ready
# Solution: Add health check
services:
  postgres:
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

Best Practices from Experience

1. Use npm ci Instead of npm install

# ❌ Don't use npm install
- run: npm install

# ✅ Use npm ci (faster, more reliable)
- run: npm ci

2. Cache Dependencies

- uses: actions/setup-node@v3
  with:
    node-version: '18'
    cache: 'npm'  # Speeds up subsequent runs

3. Fail Fast

jobs:
  test:
    steps:
      - run: npm run lint
      - run: npm run type-check
      - run: npm test  # Only runs if above succeed

4. Use Descriptive Names

# ❌ Bad
- run: npm test

# ✅ Good
- name: Run unit and integration tests
  run: npm test

5. Organize Steps Logically

steps:
  # 1. Setup
  - name: Checkout code
  - name: Setup Node.js
  
  # 2. Install
  - name: Install dependencies
  
  # 3. Check
  - name: Lint
  - name: Type check
  
  # 4. Test
  - name: Run tests
  
  # 5. Report
  - name: Upload coverage

Conclusion

GitHub Actions transforms how we develop and deploy software. In this part, we covered:

• What GitHub Actions is and why it's valuable

• Core concepts: workflows, jobs, steps, runners, actions

• Creating your first CI workflow for a TypeScript microservice

• Real-world examples from production projects

• Common triggers and debugging techniques

• Best practices for workflow development

With this foundation, you can now automate testing for your TypeScript projects. Every push triggers automated checks, catching bugs before they reach production.

In Part 2, we'll dive deep into YAML syntax and workflow fundamentals, exploring all the configuration options available in GitHub Actions workflows.

---

Key Takeaways:

• Workflows are YAML files in .github/workflows/

• Start simple and add features gradually

• Use npm ci and caching for speed

• Service containers enable integration testing

• Branch protection ensures workflows pass before merging

Remember: The best time to set up CI/CD was at the start of your project. The second-best time is now! 🚀