Gitea Actions + Vercel = Gitea Pages

Before we embark on the journey of creating your 'GitHub Pages' alternative with Gitea Actions and Vercel, there are three essential prerequisites you need to have in place:

1. Gitea Instance: To get started, you must have a working Gitea instance up and running. If you're not already familiar with Gitea, it's a self-hosted Git service that provides you with complete control over your repositories. You can install Gitea on your own server or use a hosted instance, but you should have a Gitea instance and repository where your website's source code will reside.
2. Enable Gitea Actions: Gitea Actions is a powerful automation feature within Gitea that allows you to create custom CI/CD pipelines for your repositories. Make sure you've enabled and configured Gitea Actions for the repository you intend to deploy your website from. This will be a crucial part of automating your deployment workflow and connecting it with Vercel. Gitea Actions requires a Gitea instance of version 1.19 or higher.
3. Vercel Account: You'll need a Vercel account to take advantage of Vercel's hosting platform and use the Vercel CLI for deployment. If you don't have an account, you can sign up for free on the Vercel website.

Getting this set up requires some technical knowledge and can be tricky. Leave a comment if you're stuck on something, or try other channels such as the Gitea Slack or the Gitea Discord to get help.

Before we dive into creating your 'GitHub Pages' alternative, let's quickly familiarize ourselves with Gitea Actions and how to set up the necessary CI/CD workflow. It's worth noting that Gitea Actions is compatible with GitHub Actions, although some features may be disabled in comparison. It uses the same GitHub Actions syntax as GitHub Actions, so you can use the same syntax to define your deployment workflow.

Creating a Workflow YAML File

In your Gitea repository, you'll need to create a .gitea/workflows directory if it doesn't already exist. Inside this directory, add a YAML file to define your workflow. Let's take a look at a simple example:

name: Gitea Actions Demo
run-name: ${{ gitea.actor }} is testing out Gitea Actions
on: [push]

jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "The job was automatically triggered by a ${{ gitea.event_name }} event."
      - run: echo "This job is now running on a ${{ runner.os }} server hosted by Gitea!"
      - run: echo "The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v3
      - run: echo "The ${{ gitea.repository }} repository has been cloned to the runner."
      - run: echo "The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ gitea.workspace }}
      - run: echo "This job's status is ${{ job.status }}."

This example YAML file defines a workflow named "Gitea Actions Demo." It triggers on every push event to your repository. When an event occurs, it runs on an Ubuntu-based runner provided by Gitea Actions.

If you try to just push this .yaml file to your repository, it is possible that the workflow does not yet run. Currently (I tried Gitea v1.20.5), Gitea Actions must be manually enabled on the instance, as well as manually enabled for each repository.

You can check the status of the workflow by visiting the Actions tab of your repository.

Move on to the next step once you have this sample workflow running.

Now that you've tested your Gitea Actions workflow, it's time to embark on the journey of deploying your website to Vercel. To interact with Vercel's hosting platform and automate various deployment tasks, we'll rely on the Vercel Command Line Interface (CLI). The Vercel CLI allows you to deploy your web projects, manage your deployments, and even create serverless functions directly from your terminal.

To begin the deployment process, the first step is to run vercel init using the Vercel CLI.

In order to do that, install the Vercel CLI:

1. Make sure you have Node.js and npm installed.
2. Run npm install -g vercel to install the Vercel CLI globally.

With the Vercel CLI installed, you're ready to initiate your project on Vercel. Run vercel init in the root of your project. This command initializes your project on Vercel, creating a connection between your local development environment and the Vercel platform.

The command will guide you through the setup process, prompting you to log in to your Vercel account, select your project's name, and configure other settings relevant to your project. Once done, you should find a .vercel folder in your project, containing a project.json file. This file contains two important keys that uniquely identify your project on Vercel:

{
  "orgId": "D788EY9028KJ...",
  "projectId": "prj_JE3958DKL2L..."
}

These identifiers, orgId and projectId, are essential for interacting with the Vercel platform. They help the Vercel CLI understand which project your deployment is associated with, ensuring that your website is deployed to the correct destination within your Vercel account. Let's add these keys to the Gitea repo's secret keys, so that our workflow is able to use them.

In the context of Gitea Actions and Vercel, you'll need to create and configure secret variables within your Gitea repository. These secret variables will be used in your deployment workflow to authenticate and interact with Vercel's platform. Here's how to set them up:

1. Navigate to your repository's settings page.
2. Click on the Actions tab on the left.
3. Select the Secrets entry.
4. Click on Add secret.
5. Enter the name and value of the secret. The names should be VERCEL_ORG_ID and VERCEL_PROJECT_ID for the two keys mentioned in the previous section, with their corresponding values.
6. Click on Add secret.

A third secret variable is required for the Vercel CLI to authenticate with Vercel, and that is the VERCEL_TOKEN. This token serves as your project's key to access Vercel's platform securely. It acts as your digital identity, allowing the Vercel CLI to deploy your website to the cloud and manage project-specific settings.

Follow these steps to generate your VERCEL_TOKEN:

1. Make an account or log in at https://vercel.com
2. Go to https://vercel.com/account/tokens
3. Click on the Create button, then enter "Gitea Actions" as the token name
4. Click Create Token and save the code that is given to you. We will need this for later and Vercel will not show it again.

Now add this VERCEL_TOKEN secret to your repository, as you did with the two other keys.

The end result should look something like this:

Important: never store your VERCEL_TOKEN or any other secret in a public repository. It is a secret and should not be shared with anyone.

Now that we have our secrets in place, we can start writing our first Vercel workflow. Doing a quick google search I found a tutorial that explains how to use GitHub Actions to deploy to Vercel. Since Gitea Actions should be compatible with Gihub Actions, we can copy it:

name: Vercel Preview Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches-ignore:
      - main
jobs:
  Deploy-Preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

Note that the secret keys that we set up in the previous section are used here to be able to execute the workflow. The env section sets up the required environment variables using the secrets you've configured earlier. The workflow is triggered by push events, but it specifically ignores pushes to the main branch. This ensures that preview deployments are triggered for feature branches and not the main production branch. In case you still use the master branch name, you can just replace main with master.

The different steps define the tasks that will be executed. It includes steps to check out the code, install the Vercel CLI, pull environment information, build project artifacts, and finally deploy those artifacts to Vercel. It's quite straighforward, since the vercel command does all the technical stuff. The Vercel command is compatible with many front-end frameworks and technologies such as React, Vue.js, Angular, Next.js, Gatsby, Svelte and plain HTML/CSS/Javascript. It automatically detects which framework is used, and should work out-of-the-box for any of these options.

Copy this file to .gitea/workflows/vercel-preview.yaml and push it to your repository. You should now see your workflow running, and soon after your website should be online on a temporary subdomain. You can check out the preview by navigating to your vercel dashboard at https://vercel.com/dashboard.

Everything working as expected? Awesome.
Now we can add a second workflow, which should deploy our production build to Vercel, whenever a new commit is pushed to the main branch.

name: Vercel Production Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches:
      - main
jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

We've explored how to combine Gitea Actions with Vercel to create a GitHub Pages alternative. Gitea Actions is a potent automation feature that empowers you to craft custom CI/CD pipelines for your repositories, automating your deployment process and ensuring your website is consistently up-to-date. Vercel, on the other hand, furnishes a top-tier hosting platform renowned for its user-friendliness and developer-centric focus. It excels in speed, scalability, and ease of use, rendering it an exceptional choice for hosting your 'GitHub Pages' substitute. Lastly, we've delved into the importance of managing deployment secrets, a critical element in securing your deployment workflow. It's crucial to ensure that sensitive information such as VERCEL_ORG_ID, VERCEL_PROJECT_ID, and VERCEL_TOKEN remains confidential by configuring them as secret variables in your Gitea repository.

Now that you have successfully created your 'GitHub Pages' alternative, here are some suggested next steps:

• Custom Domain Setup: Consider setting up a custom domain for your new web project.
• Serverless Functions: If your project requires dynamic functionality, consider integrating serverless functions.