Publish to Netlify using Gitea or Forgejo Actions

Publish to Netlify using Gitea or Forgejo Actions

Netlify's built-in auto-deploy support is quite nice, but is sadly limited only to hosted versions of GitHub, GitLab, Bitbucket, and Azure DevOps. Self-hosted support of some of these is further limited to their Enterprise plan only.

Fortunately with Gitea (and Forgejo) Actions we can still enjoy automatic deploys to Netlify, by writing up a relatively simple Action. This should work whether you self-host Gitea or Forgejo, or make use of one of the hosted offerings like Codeberg or something your favorite community of choice has set up.

Let's get started.

💡
This guide assumes you already have a working Gitea or Forgejo environment with Actions enabled and at least one runner set up. If you've not yet done so, please follow Gitea's or Forgejo's documenation first.

I have prepared a basic action that you can pretty much copy-paste and use in your own Node-based projects. The biggest part that may need adjusting is whatever build steps your particular website or -app needs, and which specific Netlify deploy options you might want to set.

Let's take a look at the complete yaml workflow file, and then go over the important parts below.

name: 'Deploy to Netlify'

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: 'Deploy to Netlify'
    steps:
      - uses: actions/checkout@v3
        name: Checkout
      - name: Build
        run: |
          npm --version && node --version
          npm ci --no-update-notifier
          npm run build
      - uses: https://github.com/nwtgck/actions-netlify@v2.0
        name: Deploy
        with:
          publish-dir: './dist'
          production-deploy: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: "Deployed from Gitea Action"
          enable-commit-comment: false
          enable-pull-request-comment: false
          overwrites-pull-request-comment: true
          enable-github-deployment: false
        env:
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
        timeout-minutes: 1

You can add and customize this file to your repository inside the `.github/actions

Let's go over some of the specifics now.


On

on:
  push:
    branches:
      - main

This example configuration is configured to react to two types of interactions; whenever a new commit is pushed to the main branch. At the time of writing the workflow_dispatch manually triggered option is not yet available. Once that functionality is made available, one might consider adding it here too.

As of Gitea version 1.21.0, the cron option is available too now, a very powerful option for scheduled actions that really open up what you can do with Actions.

Common Steps

  - uses: actions/checkout@v3
    name: Checkout

A fundamental step in most every action and mostly self explanatory; this checks out the current repository so that you are able to work with your project's source code in subsequent steps.

  - name: Build
    run: |
      npm --version && node --version
      npm ci --no-update-notifier
      npm run build

An example build step for a NodeJS project. The first line simply prints out both npm and node versions, which can be useful when debugging Actions logs.

The second line runs the "clean install" variant of install. A full explanation on the differences is a bit outside the scope of this article, but the most important difference is that clean-install never writes/updates package.json nor package-lock.json and instead errors out if what is defined in these files does not match with one another.

The last line is a placeholder for whatever command you'd need to run to build your project.

The Netlify publish step

  - uses: https://github.com/nwtgck/actions-netlify@v2.0
    name: Deploy
    with:
      publish-dir: './dist'
      production-deploy: true
      github-token: ${{ secrets.GITHUB_TOKEN }}
      deploy-message: "Deployed from Gitea Action"
      enable-commit-comment: false
      enable-pull-request-comment: false
      overwrites-pull-request-comment: true
      enable-github-deployment: false
    env:
      NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    timeout-minutes: 1

With great thanks to Ryo Ota for writing this action and making this all possible, let's go over the values we may want to set here to make deploys work.

Required values

  • publish-dir — The (relative) path to the directory that should be published to Netlify, usually the one containing the results of your build steps. E.g. ./dist.
  • NETLIFY_AUTH_TOKEN — Your Netlify personal access token. You can generate this from your Netlify user settings page.
  • NETLIFY_SITE_ID — The Site ID (UUID) Netlify has assigned to your site. This can be found by visiting the "Site configuration" view of your site on Netlify. It's listed right in the "Site information" section as "Site ID."

Additional settings

The above example has some additional settings defined. These can be fully customized to your liking, but keep in mind that this Action is originally written with GitHub in mind, some some functions might not work in a Gitea context. I recommend reading through this Action's README so you can decide which values might work well for your specific needs.

Partial screenshot of the Netlify Dashboard, showing several production deploys that have been triggered by this Gitea Action approach.

Closing thoughts

While it takes a little more effort as compared to just using Netlify's dashboard to connect up with a GitHub repository, it's fortunately not all too challenging to get things working this way from your (self-hosted) Gitea or Forgejo instance.

There's a lot more you can do with Gitea Actions. Feature-wise it's very close to GitHub Actions, though not exactly the same. Some key differences are described here and are good to keep in mind when writing up your own Actions.

I hope this is helpful to some of you out there and can help you at least consider making the switch to using an option other than GitHub for your own, your clients', or employer's needs.

Thank you.