README.md

GITHUB ACTIONS HANDS-ON

Welcome to the GitHub Actions kata Ekino!
(For Node.js project)

What is GitHub Actions?

GitHub Actions is a CI/CD platform that allows you to automate your build, test, and deployment pipeline directly from your GitHub repository. It uses workflows defined in .github/workflows directory to execute jobs triggered by events like pushes, pull requests, or scheduled tasks.

Prepare

• Clone the repository

git clone https://github.com/ekino/githubworkflow-handson-nodejs.git
cd githubworkflow-handson-nodejs

• Create a branch with your name
  Example:

git checkout -b john
# git switch -c john

• Install the project dependencies

npm install

• Create the first empty commit from your account

git commit --allow-empty -m "Init kata john"

🚀 Create Your First GitHub Actions Workflow

Expand

1. Create a .github/workflows directory in the root of your project if it doesn't exist:

mkdir -p .github/workflows

2. Create a new workflow file, for example ci.yml:

touch .github/workflows/ci.yml

3. Modify the ci.yml file:

name: CI Pipeline

on:
  push:
    branches:
      - john #replace by your branch name

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

4. Commit and push your workflow file:

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

Once you push your changes, GitHub will automatically trigger the workflow.

5. Open your GitHub repository in a browser and navigate to the Actions tab to see your workflow running 🚀.

🔍 Explanation

• name: Sets the name of the GitHub Actions workflow.

• on: Defines when the pipeline should run:

  • On each push to the main branch.

• jobs: Defines the list of jobs to run.

• install:

• runs-on:

  • ubuntu-latest: Specifies that the job will run on an Ubuntu environment.

  • steps: Lists the steps of the job:

    1. Checkout repository – Clones the repository.
    
    2. Setup Node.js – Uses the latest Node.js 22 version.
    
    3. Install dependencies – Runs npm ci to install dependencies.
    

🚀 Using Artifacts and Cache in GitHub Actions

In GitHub Actions, artifacts and cache serve similar purposes as in GitLab CI:

• Artifacts are files generated during a job that you want to persist and share between stages (e.g., build outputs, test reports).
• Cache helps store dependencies or frequently used files to speed up workflow runs.

🔗 Refer to the GitHub Actions documentation on caching and artifacts for more details.

📝 Exercise

1. Enhance the install job to include artifacts and cache configurations:

   • Artifacts: Save node_modules/ as an artifact and set an expiration time of 2 weeks.
   • Cache: Use a cache key based on package-lock.json and enable pull-push behavior to reuse dependencies across jobs.

2. Commit your updated workflow

   • Push your changes to trigger the GitHub Actions workflow.

🎯 Correction

Expand

name: CI Pipeline

on:
  push:
    branches:
      - john

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: node-modules-${{ hashFiles('package-lock.json') }}
          restore-keys: node-modules-

      - name: Install dependencies
        run: npm ci

      - name: Upload node_modules as an artifact
        uses: actions/upload-artifact@v4
        with:
          name: node-modules
          path: node_modules
          retention-days: 14

🔍 Explanation

actions/cache:

• Caches node_modules/ based on package-lock.json.
• If package-lock.json changes, a new cache is created.
• Uses restore-keys for fallback cache retrieval.

actions/upload-artifact:

• Saves node_modules/ as an artifact.
• The artifact remains available for 2 weeks (14 days).

💡 This setup ensures faster builds by caching dependencies and preserving files across jobs! 🚀

🚀 Adding a Lint Job in GitHub Actions

Linting helps detect potential errors, enforce coding standards, and maintain code quality.
By adding a lint job in the pipeline, we ensure that all code adheres to best practices before merging changes.

🔗 Refer to the GitHub Actions documentation to learn more about job dependencies.

📝 Exercise

Enhance the workflow by:

1. Creating a new stage called check.
2. Adding a lint job that runs biome ci using the Setup Biome GitHub Action.
3. Commit your updated workflow
   • Push your changes to trigger the GitHub Actions workflow.
   • Verify that the lint job runs successfully in the Actions tab. 🚀

🎯 Correction

Expand

name: CI Pipeline

on:
  push:
    branches:
      - john

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: node-modules-${{ hashFiles('package-lock.json') }}
          restore-keys: node-modules-

      - name: Install dependencies
        run: npm ci

      - name: Upload node_modules as an artifact
        uses: actions/upload-artifact@v4
        with:
          name: node-modules
          path: node_modules
          retention-days: 1

  lint:
    runs-on: ubuntu-latest
    needs: install # Ensures the install job completes first
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Biome CLI
        uses: biomejs/setup-biome@v2 # The action will look for the version of the @biomejs/biome dependency in the lockfiles of popular package managers such as npm.

      - name: Run Biome
        run: biome ci # Files won’t be modified, the command is a read-only operation.

🔍 Explanation

TODO

Happy automating!