DEV Community

Raul Melo
Raul Melo

Posted on • Originally published at raulmelo.me

Deploying on Netlify via GitHub Actions: A Seamless Guide

#netlify #githubactions #deploy #javascript

Netlify is a fantastic platform.

As developers, sometimes we don't want to spend much time figuring out how to deploy our apps, setting up servers, AWS accounts, etc. Here's where products like Netlify shine by abstracting all this complexity away from us and providing easy-to-use dashboards.

But all these facilities come with a price.

On Netlify, for example, if we use the basic and free plan, we have a few limitations, like the number of contributors we can have, the amount of network bandwidth, how many websites we can host, etc.

One that recently pissed me off a lot is the amount of build minutes.

I have a few projects at the same account (team), plus some automated processes to update my dependencies, which drained my build minutes in two weeks.

What made me angry was that Netlify thought it would be a good idea to charge me 7 dollars automatically (without giving me a chance to say NO) for extra build minutes. Because I didn't have a credit card, my account was almost suspended until I paid it.

So, I've decided to do something about it, which is being away to use their infrastructure to run my builds, and here we are.

Let's dive deep into how to handle the builds through GitHub Actions.

Netlify host, builds, and previews

When we integrate a project directly from our GitHub and use Netlify as a host, we have to specify a bunch of info, including how to build our app and where the dist files are located.

By doing that, on every push in our GitHub repository, our code will be synced with Netlify, which will install dependencies, run the build, and deploy. Depending on your tools and project size, this can go from a few seconds to minutes.

By default, every project has a very nice feature called build preview, which builds your project and hosts it on another URL, making it possible to see a preview of your app with the changes you have made.

This is incredible, but it hits hard on the build times.

Imagine your project takes 1 minute to build, and you push 10 times to your feature branch. For a single feature, we're talking about 3%~ of your monthly build minutes quota.

If you have something like Dependabot or Renovate that creates PRs automatically to update dependencies, then you almost have no control over how fast the quota can go.

There are ways to mitigate that, though. You can turn off the deploy preview, which sucks because this is such a nice feature.

Also, if you're in a monorepo, you can prevent building a preview if the code touched isn't part of the project hosted on Netlify using the ignore builds feature.

Or if you already use GitHub Actions to do the deployment, in case you already use it to run checks, tests, or code quality.

Deploying to Netlify through GitHub Actions

To demonstrate how to do that, I'm going to use the following setup, but you can abstract the concept and adapt it to your tooling:

  • Node v20.10.0
  • npm v10.2.3 (to lower the entry bar)
  • vite + svelte starter project (build static)
  • netlify-cli v17.10.1

Creating the basic Github Action Workflow

With the project created, let's jump straight to where the magic will happen.

I will create a deploy workflow, but feel free to hook the deployment steps into your existing workflow.

.github/workflows/deploy.yml

name: Deploy website

on: [push]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Checkout
        uses: actions/checkout@v4

      - name: Setup NodeJS
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install Dependencies
        run: npm ci
Enter fullscreen mode Exit fullscreen mode

Breaking it down:

  • on every push
  • We run on an ubuntu machine the following steps:
    • do a git checkout to fetch the code
    • setup node JS using version 20 and use npm cache strategy
    • install our project dependencies

When we push this code, the pipeline should run successfully:

Successful workflow run

Ok, before we finish this setup, let's create a project on Netlify.

Netlify project

I don't want to create a connection between my Github project and Netlify or drop build files there. So, to cut to the chase, I will use the Netlify CLI to create the project.

The first step is installing the Netlify CLI globally on my machine:

npm install netlify-cli -g
Enter fullscreen mode Exit fullscreen mode

Now, we need to log in with our account:

netlify login
Enter fullscreen mode Exit fullscreen mode

They will ask you to open a link in your browser and log in.

After that, we can create the project:

netlify sites:create
Enter fullscreen mode Exit fullscreen mode

You'll need to fill in some information, like the team and site names.

After finishing, you'll have your site details, such as your Admin URL, Site URL, and Site ID.

$ netlify sites:create
? Team: test
? Site name (leave blank for a random name; you can change it later): netlify-deploy-gha

Site Created

Admin URL: https://app.netlify.com/sites/netlify-deploy-gha
URL:       https://netlify-deploy-gha.netlify.app
Site ID:   87c1c6cb-5eae-4797-8c20-58608f633a98

Adding local .netlify folder to .gitignore file...
Linked to netlify-deploy-gha
Enter fullscreen mode Exit fullscreen mode

If you open your Admin URL, you will see an empty project because we haven't done a deployment yet.

Before going back to the GitHub part, we'll need to save two pieces of information we'll use there: the Site ID and generate an API token.

The Site ID you already have, so now let's create an API Token.

Generate Netlify API Token

Attention
If for some reason you can't follow this section, search on Netlify about "Personal access tokens"

First, access your User Settings, then click on Applications. There, you'll find a section called Personal Access Tokens. Click on New access token:

New access token

Now, give your token a name and choose when it expires:

Token details

After clicking to create your token, copy the value and save it somewhere:

Token created

Now, let's head back to the GitHub actions part:

Deploy setup

To do the deployment, we have to add a few steps to our workflow.

We need to:

  • Ensure we have Netlify CLI globally in our environment
  • Run the build command so we can send those files to Netlify 
name: Deploy website

on: [push]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Checkout
        uses: actions/checkout@v4

      - name: Setup NodeJS
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install Netlify
        run: npm install netlify-cli@17.10.1 -g

      - name: Install Dependencies
        run: npm ci

      - name: Build project
        run: npm run build
Enter fullscreen mode Exit fullscreen mode

I always install pinned versions because a major version update e.g., from 17 to 18, could suddenly break my setup.

Before adding the deploy command, we need to add the Site ID and the API Token to our project environment variables.

These values are secrets and can't be hard-coded in our code.

Adding GitHub secrets

In your project, click on Settings, then Secrets and variables, Actions, and New repository secret.

Create two variables:

  • NETLIFY_SITE_ID => will hold your Netlify Site ID
  • NETLIFY_API_TOKEN => will hold your Netlify API personal token

GitHub actions secrets

Deploy command

Finally, let's add the deploy command.

Before doing that, you must know what folder is produced when you run your build command.

On Vite's projects, usually, this folder is called dist, but in other frameworks, it could be something like build.

name: Deploy website

on: [push]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Checkout
        uses: actions/checkout@v4

      - name: Setup NodeJS
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install Netlify
        run: npm install netlify-cli@17.10.1 -g

      - name: Install Dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Deploy to Netlify
        id: netlify_deploy
        run: |
          netlify deploy \
            --dir dist \
            --site ${{ secrets.NETLIFY_SITE_ID }} \
            --auth ${{ secrets.NETLIFY_API_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

If you configured everything correctly, when we push this file, the pipeline will run and deploy a preview of your site.

GHA deploy step info

The field 'Website draft URL' holds the deployment preview URL.

Website deployed

Though it's working, we are not deploying to production yet.

Let's do some tweaks to consider this case.

Production deployment

Deploying previews is useful only when pushing to any branch but our main branch.

Also, if we want to deploy to production, we must pass a --prod flag.

So, we can do some bash code with these two pieces of information.

.github/workflows/deploy.yml

name: Deploy website

on: [push]

env:
  BRANCH_NAME: ${{ github.ref_name }}

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Checkout
        uses: actions/checkout@v4

      - name: Setup NodeJS
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install Netlify
        run: npm install netlify-cli@17.10.1 -g

      - name: Install Dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Deploy to Netlify
        id: netlify_deploy
        run: |
          prod_flag=""
          if [ "$BRANCH_NAME" = "main" ]; then prod_flag="--prod"; fi
          netlify deploy \
            --dir dist \
            --site ${{ secrets.NETLIFY_SITE_ID }} \
            --auth ${{ secrets.NETLIFY_API_TOKEN }} \
            $prod_flag
Enter fullscreen mode Exit fullscreen mode

Breaking the changes down:

  • on lines 5 and 6, we declare that, in all steps, we'll have access to an environment variable called BRANCH_NAME. We'll use it to determine if it's the main branch or not
  • on line 33, we create a bash variable called prod_flag
  • on line 35, we assert against our BRANCH_NAME. If it's main or whatever your main branch is named, we add the --prod to the prod_flag variable
  • on line 39, we append the prod_flag variable. It might be --prod or an empty string (for deploy previews)

Our "Deploy to Netlify" step will produce a different out when we push these changes. Instead of "Website draft URL", we'll have "Website URL", the production one.

# ...

Build logs:        https://app.netlify.com/sites/netlify-deploy-gha/deploys/6590b2e90ce0fbbf1abd9ac1
Function logs:     https://app.netlify.com/sites/netlify-deploy-gha/functions
Unique deploy URL: https://6590b2e90ce0fbbf1abd9ac1--netlify-deploy-gha.netlify.app
Website URL:       https://netlify-deploy-gha.netlify.app
Enter fullscreen mode Exit fullscreen mode

Which means we accomplished what we wanted.

Bonus: Pull Request URL comment

When we integrate GitHub + Netlify and open a PR, they have a bot that gets the Deploy preview URL and posts a comment.

This is nice because right now if we want to see the URL of our preview, we need to click to see the details of our runner, expand the "Netlify Deploy" step, search for "Website draft URL", copy the link, and open it.

In other words, we kinda lost a very nice DX by handling the integration, and that means we must do something about it.

Again, there are many ways you can approach this, I'll just give a suggestion by adding a few more steps with some bash code and JavaScript via actions/github-script.

Getting the Website draft URL

We need to get the URL of our draft so we can comment on our PR.

Let's save the output of our deploy command into a file:

.github/workflows/deploy.yml

#... rest of file

 - name: Deploy to Netlify
   id: netlify_deploy
   run: |
     prod_flag=""
     if [ "$BRANCH_NAME" = "main" ]; then prod_flag="--prod"; fi
     netlify deploy \
       --dir dist \
       --site ${{ secrets.NETLIFY_SITE_ID }} \
       --auth ${{ secrets.NETLIFY_API_TOKEN }} \
-      $prod_flag
+      $prod_flag \
+      > deploy_output.txt
Enter fullscreen mode Exit fullscreen mode

With > deploy_output.txt, every output produced will be saved in the deploy_output file.

Now, let's add another step that will read this file, extract the URL, and make it available for the following steps:

.github/workflows/deploy.yml

# ... rest of the file ...

- name: Generate URL Preview
  id: url_preview
  if: ${{ env.BRANCH_NAME != 'main' }}
  run: |
    NETLIFY_PREVIEW_URL=$(cat deploy_output.txt | grep "Website draft URL: " | cut -d' ' -f4)
    echo "NETLIFY_PREVIEW_URL=$NETLIFY_PREVIEW_URL" >> "$GITHUB_OUTPUT"
Enter fullscreen mode Exit fullscreen mode

Breaking it down:

  • we must define an id so we can get the output in another step
  • in the if clause, we only run this when it's not main
  • then, we concat some bash commands where we:
    • get the content of the deploy_output.txt file
    • extract the content of "Website draft URL: " entirely using grep;
    • split the line into fields delimited by spaces -d and then select the fourth field -f4, which is where the URL is expected to be based on your output sample
    • save the result of this operation on a variable called NETLIFY_PREVIEW_URL
  • finally, we say to GitHub Actions that this step will have an output called NETLIFY_PREVIEW_URL with its value

To test if it's working, we can simply add another step after this:

.github/workflows/deploy.yml

# ... rest of the file ...

- name: DEBUG=WILL BE REMOVED
  run: echo ${{ steps.url_preview.outputs.NETLIFY_PREVIEW_URL }}
Enter fullscreen mode Exit fullscreen mode

Print preview URL

Posting URL preview as PR comment

Now we have access to the URL, we can use it to create a PR comment.

Here it'll be raw and dirty; feel free to enhance that in a script, a more fancy message, update an existing comment, etc.

To achieve that, I'm going to use a GitHub action called github-script.

In case you don't know, this action gives us access to Github's REST API, the runner context, etc., and lets us script with JavaScript syntax without having to install anything.

The first step is to give our workflow permission to write on pull requests:

.github/workflows/deploy.yml

name: Deploy website

on: [push]

env:
  BRANCH_NAME: ${{ github.ref_name }}

permissions:
  pull-requests: write

# ... rest ...
Enter fullscreen mode Exit fullscreen mode

Then, as the last step, we can add the following code:

.github/workflows/deploy.yml

# ... rest ...

- name: Comment URL Preview on PR
  uses: actions/github-script@v7
  if: ${{ env.BRANCH_NAME != 'main' }}
  env:
    NETLIFY_PREVIEW_URL: ${{ steps.url_preview.outputs.NETLIFY_PREVIEW_URL }}
  with:
    script: |
      async function comment(){
        const result = await github.rest.repos.listPullRequestsAssociatedWithCommit({
          owner: context.repo.owner,
          repo: context.repo.repo,
          commit_sha: context.sha,
        })

        const issueNumber = result.data[0].number

        if(issueNumber){
          await github.rest.issues.createComment({
            issue_number: issueNumber,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: 'Preview URL: ' + process.env.NETLIFY_PREVIEW_URL
          })
        }else{
          console.log('No PR found for commit ' + context.sha)
        }
      }

      comment()
Enter fullscreen mode Exit fullscreen mode

Breaking it down:

  • on line 5, we define we only want to run this step on branches different than the main branch
  • on line 7, we save the URL preview into an environment variable
  • on line 9, we add a javascript script where:
    • on lines 11 to 15, we use GitHub's SDK to fetch the pull requests with the current commit hash
    • on line 17, we save this information;
    • we save this information.
    • if there's an issue number (PR number), we create a comment with the text 'Preview URL'.

By doing this, if the PR number is found, a comment will be made by the GitHub Bot:

PR comment

And now, we finally have a minimal DX, and we can rest 😅.

Monorepo case

In case you're using a monorepo, there's just one thing you need to tweak, in the deploy command, you have to add a flag called --filter with the project name:

.github/workflows/deploy.yml

#... rest of file

- name: Deploy to Netlify
  id: netlify_deploy
  run: |
    prod_flag=""
    if [ "$BRANCH_NAME" = "main" ]; then prod_flag="--prod"; fi
    netlify deploy \
      --dir dist \
      --site ${{ secrets.NETLIFY_SITE_ID }} \
      --auth ${{ secrets.NETLIFY_API_TOKEN }} \
+    --filter <my-project-name> \
      $prod_flag \
      > deploy_output.txt
Enter fullscreen mode Exit fullscreen mode

Why not...

... use the official action from Netlify?

If you encountered the official Netlify's Github Action that provides the CLI out of the box, you might notice that the last time it was updated (at least when I'm writing this post was a year ago).

I tried, but I got some version conflict problems. It seems I was trying to use an argument that wasn't present in the CLI version of the step.

.... use the "action-netlify-deploy"?

This is an open-source action that abstracts most of the setup we've made here.

I started using it, but I encountered an issue where it didn't output correctly the Preview URL. So I thought: "If I need to use a third-party action that doesn't do what I need, then I can do it by myself".

Conclusion

There is a trade-off between leaving the control of processes with the platform and taking the reins of your deployment. It's up to you to decide what is more worthwhile.

I hope with this guide, you at least can have another option to make the decision that fits you best.

Cheers.

References

Top comments (0)

Read next

radubrehar profile image

The best testing strategies for frontends

Radu Brehar👨‍💻 -

titusefferian profile image

How to use Stable Diffusion 3 to generate a similar image.

Titus Efferian -

ahgsql profile image

Building a Better RAG: A Practical Guide to Two-Step Retrieval with LangChain

ahgsql -

devmirx profile image

Learn React Hydration in 5 minutes

LordCodex -