Manually Create Coverage Badges Using GitHub Actions


Adding a coverage badge to your repository is an excellent way to demonstrate your project's test coverage and maintain a high level of code quality. By the end of this guide, you will be able to generate a dynamic coverage badge that updates automatically with each new push to your repository.

## Prerequisites

- A [Node.js](https://nodejs.org/) project with test coverage reports generated by a tool like [c8](https://github.com/bcoe/c8) or [Istanbul](https://github.com/istanbuljs/nyc).
- A GitHub repository for your project.
- [GitHub deploy keys](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) configured for your repository.

Let's get started!

## Step 1: Install Cheerio

Before anything else, make sure you have a coverage report generated by your testing tool. In our case, we will use the HTML report generated by [c8](https://github.com/bcoe/c8). This report will look something like this:

```html filename=./coverage/index.html
<!DOCTYPE html>
<html lang="en">
  <body>
    <div class="wrapper">
      <div class="pad1">
        <div class="clearfix">
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Statements</span>
            <span class="fraction">786/786</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Branches</span>
            <span class="fraction">74/74</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">90.9%</span>
            <span class="quiet">Functions</span>
            <span class="fraction">33/33</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Lines</span>
            <span class="fraction">786/786</span>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```

We will use [cheerio](https://github.com/cheeriojs/cheerio), a [jQuery](https://jquery.com/)-like library for server-side to extract the percentage data from the HTML. Install it to your `devDependencies` using the package manager of your choice:

```bash
# npm
npm install --save-dev cheerio

# yarn
yarn add --dev cheerio

# pnpm
pnpm add --save-dev cheerio
```

## Step 2: Create a Script to Extract Coverage Data

Next, we need to create the actual script that will extract the coverage data from the HTML report. Create a new file called `./scripts/generate-badges.js` and add the following code:

```js filename=./scripts/generate-badges.js
const fs = require('fs');
const https = require('https');
const cheerio = require('cheerio');

const coverageFile = './coverage/index.html';
const badgesDir = './coverage/badges';

// Read the coverage HTML file.
fs.readFile(coverageFile, 'utf-8', (err, data) => {
  if (err) {
    console.error(`Error reading coverage file: ${err}`);
    process.exit(1);
  }

  // Parse the HTML using Cheerio.
  const $ = cheerio.load(data);

  // Construct the shields.io URL for each badge.
  const statementsBadgeUrl = generateUrl('statements', extractPercentage($, 1));
  const branchesBadgeUrl = generateUrl('branches', extractPercentage($, 2));
  const functionsBadgeUrl = generateUrl('functions', extractPercentage($, 3));
  const linesBadgeUrl = generateUrl('lines', extractPercentage($, 4));

  // Create the badges directory if it does not exist.
  if (!fs.existsSync(badgesDir)) {
    fs.mkdirSync(badgesDir);
  }

  // Download each badge and save it to the badges directory.
  downloadBadge(statementsBadgeUrl, `${badgesDir}/statements.svg`);
  downloadBadge(branchesBadgeUrl, `${badgesDir}/branches.svg`);
  downloadBadge(functionsBadgeUrl, `${badgesDir}/functions.svg`);
  downloadBadge(linesBadgeUrl, `${badgesDir}/lines.svg`);

  console.log('Code coverage badges created successfully.');
});

/**
 * Generate a shields.io URL for a badge.
 *
 * Change the color of the badge based on the percentage.
 *
 * @param {string} text The text to display on the badge.
 * @param {number} percentage The percentage to display on the badge.
 * @returns {string} The shields.io URL.
 */
const generateUrl = (text, percentage) => {
  let color = 'brightgreen';
  if (percentage < 70) {
    color = 'red';
  } else if (percentage < 80) {
    color = 'yellow';
  } else if (percentage < 90) {
    color = 'orange';
  }
  return `https://img.shields.io/badge/coverage%3A${text}-${percentage}%25-${color}.svg`;
};

/**
 * Extract the code coverage percentage from the HTML.
 * @param {Cheerio} $ The Cheerio object.
 * @param {number} index The index of the element to extract.
 */
const extractPercentage = ($, index) => {
  const text = $(`.pad1y:nth-child(${index}) span.strong`) ?? '0';
  const percentage = text.text().trim().replace('%', '');
  return parseFloat(percentage);
};

/**
 * Download a badge from shields.io.
 * @param {string} url The shields.io URL.
 * @param {string} filename The filename to save the badge to.
 */
const downloadBadge = (url, filename) => {
  https.get(url, (res) => {
    if (res.statusCode !== 200) {
      console.error(`Error downloading badge: ${res.statusMessage}`);
      return;
    }

    const file = fs.createWriteStream(filename);
    res.pipe(file);
    file.on('finish', () => {
      file.close();
    });
  });
};
```

This is a fairly straightforward script that uses Cheerio to parse the HTML report and extract the coverage data. It then uses the data to generate the [shields.io](https://shields.io/) URLs for each badge type. Finally, it downloads each badge and saves it to the `./coverage/badges` directory.

Update your `package.json` to add a new script that will run the `generate-badges.js` script:

```json filename=package.json
{
  "scripts": {
    // ...
    "generate-badges": "node ./scripts/generate-badges.js"
  }
}
```

Run the script to generate the badges:

```bash
# generate the coverage report first
pnpm coverage

# generate the badges
pnpm generate-badges
```

## Step 3: Configure GitHub Actions

> **NOTE**: For this guide, we will use [pnpm](https://pnpm.io/), but the commands should be similar for other package managers.

> **NOTE**: This requires that you have an SSH Deploy Key configured for your repository. See [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) for more information.

In your repository, create a `.github/workflows` directory if it doesn't already exist. Then, create a new YAML file inside the workflows directory called `coverage-badge.yml`. This file will define the GitHub Actions workflow that generates the coverage badge.

Add the following content to `coverage-badge.yml`:

```yaml filename=.github/workflows/coverage-badge.yml
name: (main) coverage badge

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  coverage-badge:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v3
      - name: setup node
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: install pnpm
        uses: pnpm/action-setup@v2
        id: pnpm-install
        with:
          version: ${{ matrix.pnpm }}
          run_install: false
      - name: get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-
      - name: install dependencies
        run: pnpm install
      - name: run coverage
        run: pnpm coverage
      - name: generate badges
        run: pnpm generate-badges
      - name: push coverage artifacts to another branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
          publish_dir: ./coverage
          publish_branch: coverage
          allow_empty_commit: true
```

Let's break down the workflow into its various sections:

```yaml
on:
  workflow_dispatch:
  push:
    branches:
      - main
```

The workflow is triggered when there's a push to the `main` branch or can be triggered manually ([`workflow_dispatch`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch)).

```yaml
jobs:
  covera:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
```

We're using a matrix strategy to run the workflow on multiple operating systems, Node.js versions, and pnpm versions. For our purpose, we will only use one version of each, but this is a good practice to follow.

```yaml
- name: checkout repository
  uses: actions/checkout@v3
- name: setup node
  uses: actions/setup-node@v3
  with:
    node-version: ${{ matrix.node }}
```

This step checks out your repository using the [actions/checkout](https://github.com/actions/checkout) action. Then, it sets up Node.js using the [actions/setup-node](https://github.com/actions/setup-node) action.

```yaml
- name: install pnpm
  uses: pnpm/action-setup@v2
  id: pnpm-install
  with:
    version: ${{ matrix.pnpm }}
    run_install: false
```

This step installs pnpm using the [pnpm/action-setup](https://github.com/pnpm/action-setup) action and the specified pnpm version from the matrix. We're not installing any dependencies yet, so we don't need to run `pnpm install`.

```yaml
- name: get pnpm store directory
  id: pnpm-cache
  shell: bash
  run: |
    echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
- name: Setup pnpm cache
  uses: actions/cache@v3
  with:
    path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      ${{ runner.os }}-pnpm-store-
- name: install dependencies
  run: pnpm install
```

These steps will use the cache from [actions/cache](https://github.com/actions/cache) and install the project's dependencies using pnpm. We're using the cache to reduce installation time and to avoid downloading the same dependencies multiple times.

```yaml
- name: run coverage
  run: pnpm coverage
- name: generate badges
  run: pnpm generate-badges
```

This step runs the `coverage` script, which should generate a coverage report. Then, it runs the `generate-badges` script, which should generate the coverage badges.

```yaml
- name: push coverage artifacts to another branch
  uses: peaceiris/actions-gh-pages@v3
  with:
    deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
    publish_dir: ./coverage
    publish_branch: coverage
    allow_empty_commit: true
```

Lastly, this step pushes the coverage artifacts, including the generated badges and the coverage report, to a separate coverage branch in your repository using the [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages) action.

Options:

- The `deploy_key` option is set to the `COVERAGE_DEPLOY_KEY` secret, which is a Deploy Key stored in your repository settings. This deploy key should have write access to the repository. Follow the instructions from [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) to generate it and add it to your repository.
- The `publish_dir` is set to `./coverage`, which is the directory containing the coverage report and badges.
- The `allow_empty_commit` option is set to true to allow empty commits if there are no changes in the coverage artifacts.
- The `publish_branch` is the name of the branch you want to push the coverage artifacts to. It's currently set to `coverage`, but you can change it to whatever you want.

## Step 4: Add Badge to README

To display the coverage badge in your README file, add the following line at the top of your `README.md` file:

```md filename=README.md
![Coverage: Statements](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/statements.svg)
![Coverage: Branches](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/branches.svg)
![Coverage: Functions](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/functions.svg)
![Coverage: Lines](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/lines.svg)
```

These lines will render the badges as an image. It should point to the latest badges in your `<PUBLISH_BRANCH_NAME>` branch.

## Conclusion

Congratulations! You have successfully created a dynamic coverage badge for your Node.js project. This badge will help you showcase your project's test coverage and encourage you to maintain a high level of code quality. Don't hesitate to customize this workflow to suit your needs and adapt it to different coverage tools and badge styles.

Happy coding!


Deploying a Repository Inside a GitHub Organization to Vercel Using GitHub Actions


[Vercel](https://vercel.com/) is a popular cloud service platform designed for hosting [Next.js](https://nextjs.org/) applications. While it offers free hosting for personal repositories, it doesn't allow deploying from repositories inside a GitHub Organization unless you subscribe to a paid plan.

In this blog post, we'll create a GitHub Action that duplicates the content of a repository inside a GitHub Organization to a repository in your personal GitHub account, allowing you to leverage Vercel's free hosting services.

> **NOTE**: This approach may not be suitable for all scenarios, and ensuring proper security measures when dealing with sensitive data is essential.

## Prerequisites

- A personal GitHub account
- A repository within a GitHub Organization (source repository)
- A separate repository in your personal account to host the copied files (destination repository)

## Step 1: Generate SSH Keys

You'll need to generate an SSH Deploy Key to securely push your content from the organization's repository to the external repository. Although you can also use a Personal Access Token, an SSH deploy key is recommended as it minimizes the impact of potential security breaches.

```bash
ssh-keygen -t ed25519 -C "$(git config user.email)" -N "" -f github-<desitination-repo-name>
```

Replace the `<desitination-repo-name>` with the name of your destination repository and run the command. Afterwards, you should now have both public and private key files:

- `github-<desitination-repo-name>.pub` (public)
- `github-<desitination-repo-name>` (private)

## Step 2: Add the private key to the Source Repository

1. Visit the source repository's GitHub page.
2. Click on "Settings" in the repository (not account settings).
3. In the left-hand pane, click "Secrets", then "Actions".
4. Click on "New repository secret".
5. Name it `SSH_DEPLOY_KEY` and paste the contents of the private key file.
6. Click "Save".

## Step 3: Add the public key to the Destination Repository

1. Visit the destination repository's GitHub page.
2. Click on "Settings" in the repository (not account settings).
3. In the left-hand side pane, click on "Deploy keys."
4. Click on "Add deploy key".
5. Paste the contents of the public key file.
6. Enable "Allow write access".
7. Click "Save".

## Step 4: Disable GitHub Actions on the Destination Repository

1. Visit the destination repository's GitHub page.
2. Click on "Settings" in the repository (not account settings).
3. Click on "Actions" and then "General".
4. Select "Disable actions".
5. Click "Save".

## Step 5: Create a GitHub Action Workflow

Create a new GitHub Action workflow in your source repository by adding a YAML file in the `.github/workflows` directory. Name the file `push-to-external-repo.yml` and paste the following content:

```yaml filename=.github/workflows/push-to-external-repo.yml
name: (main) push to external repo
on:
  push:
    branches:
      - main
jobs:
  push-to-external-repo:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repository
        uses: actions/checkout@v3
      - name: push to external repository
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.SSH_DEPLOY_KEY }}
          publish_dir: .
          external_repository: <your-username>/<destination-repo-name>
          publish_branch: main
          allow_empty_commit: true
```

Replace `<your-username>` with your GitHub username and `<destination-repo-name>` with the name of the external repository in your personal account.
This action will copy everything from your organization's repository to your personal repository, including your GitHub Action workflows, so follow [Step 4](#step-4-disable-github-actions-on-the-destination-repository) to disable GitHub Actions on the destination repository.

## Step 6: Run your workflow

Push something to your `main` branch and see it be pushed to your `<your-username>/<destination-repo-name>` repository.

## Step 7: Set up a project on Vercel

1. On Vercel's "New Project" page, choose the account linked to the project under the "Import Git Repository" section.
2. Find your personal repository in the list and select "Import".
3. Vercel will automatically detect the framework and any necessary build settings. You can configure project settings, including build and development settings and environment variables, at this stage or later.
4. Click the "Deploy" button. Vercel will create the project and deploy it based on the chosen configurations.


Deploy Hugo Site Using GitHub Actions


After creating a new project using
[Hugo's Quick Start guide](https://gohugo.io/getting-started/quick-start/), you
can then deploy to [GitHub Pages](https://pages.github.com/).

### Git Branches

For this site, we are deploying the project hosted at
[napjoseph/napjoseph.github.io](https://github.com/napjoseph/napjoseph.github.io/).

Since this is an
[Organization Pages-type repository](https://docs.github.com/en/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites),
we will be using following branches for our workflow:

```bash
$ git branch
master           # the branch that GitHub pages will serve the files from
stable           # the main development branch where all pull requests will be merged to
id_your_feature  # additional development branches for new features
```

### Add your Deploy Key

Follow the tutorial over at
[peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key)
and add an SSH deploy key for your project.

### Create your GitHub Action

Afterwards, create a directory for your workflows and add the config file for
your new action.

```bash
$ mkdir -p .github/workflows
$ touch .github/workflows/deploy.yml
```

```yaml filename=.github/workflows/deploy.yml
name: deploy-to-master

on:
  push:
    branches:
      - stable

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          persist-credentials: false

      - name: Update theme
        run: git submodule update --init --recursive

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.74.3'

      - name: Build
        run: HUGO_ENV=production hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./public
          publish_branch: master
          keep_files: false
          allow_empty_commit: true
```

### Deployment

After merging your pull requests to the `stable` branch, it should automatically
deploy to the `master` branch.


Nap Joseph Calub

Posts with the "GitHub Actions" tag