<h1id="how-to-deploy-a-static-website-from-gitea-using-git-hooks">How To Deploy a Static Website from Gitea Using Git Hooks</h1>
<h3id="introduction">Introduction</h3>
<p>The popular source code management system <ahref="https://git-scm.com">Git</a> is quite flexible when it comes to allowing you to perform various tasks when actions are taken on a repository. For example, you might want to send an email when a feature branch is merged into your main branch, or log various Git actions to a file for tracking.</p>
<p>These actions are called <strong>hooks</strong>, and there are several that you can use for various steps along the way to perform additional work within your Git workflow. For example:</p>
<ul>
<li><code>post-receive</code> hooks can be used to perform actions when a commit is pushed to the repository and are useful for CI/CD.</li>
<li><code>post-merge</code> hooks can be used to perform actions after a merge has been completed and are useful for logging and notifications.</li>
<li><code>post-checkout</code> hooks can be used to perform actions after you run <code>git checkout</code> and are useful for setting up project environments.</li>
</ul>
<p>For this tutorial, we will be looking at using the <code>post-receive</code> hook. A common usage for the hook is running some form of continuous integration or deployment. This might mean running tests or deploying a project. For this example, we will be automatically deploying changes to a static HTML site served by Nginx.</p>
<h2id="prerequisites">Prerequisites</h2>
<p>Gitea is a lightweight and flexible source code management system that will be used for the examples here, so before beginning this tutorial, you should have the following:</p>
<ul>
<li>An Ubuntu 20.04 server with a non-root user configured with <code>sudo</code> privileges as described in the <ahref="https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-20-04">Initial server setup for Ubuntu 20.04</a> tutorial.</li>
<li>Docker installed on your server as described by <strong>Steps 1 and 2</strong> of our guide on <ahref="https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04">How to Install Docker on Ubuntu 20.04</a>.</li>
<li>Docker Compose installed on your server. Follow <strong>Step 1</strong> of our guide on <ahref="https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-20-04#step-1-installing-docker-compose">How to Install and Use Docker Compose on Ubuntu 20.04</a>.</li>
<li>A domain name pointed at your server. If you are using a DigitalOcean Droplet, you can accomplish this by following our <ahref="https://docs.digitalocean.com/products/networking/dns/">Domains and DNS</a> documentation. This tutorial will use <^>your_domain<^> in examples throughout.</li>
<li>Gitea installed on the server behind Nginx, ready to interact with using Git over SSH as described in <ahref="https://www.digitalocean.com/community/tutorials/how-to-install-gitea-on-ubuntu-using-docker">How To Install Gitea on Ubuntu Using Docker</a>.</li>
</ul>
<h2id="step-1-creating-a-static-html-project-in-gitea">Step 1 — Creating a Static HTML Project in Gitea</h2>
<p>To begin with, you will need a repository set up in Gitea. Create a new repository using the <strong>+</strong> button in the upper right corner of the Gitea page. Name it something memorable such as the domain name that it will be deployed to. Fill out the rest of the new repository information and click <strong>Create Repository</strong>.</p>
<p><ahref="TODO.html"><imgalt="Creating a new repository"src="TODO"/></a></p>
<p>For this tutorial, you’ll be setting up a static site at <code>static.<^>your_domain<^></code>, but be sure to replace this with your final site’s domain. Now, wherever you plan on developing, check out that repository using <code>git clone</code>:</p>
<p>Now, create a file named <code>index.html</code> which will be served by Nginx. The following example uses <code>nano</code>. This file will contain a little bit of text that we can view in the browser.</p>
<p>Save and close the file. If you used <code>nano</code> to edit the file, you can do so by pressing <code>Ctrl + X</code>, <code>Y</code>, and then <code>Enter</code>.</p>
<p>Push your changes up to your Gitea repository:</p>
<divclass="codehilite"><pre><span></span><code>git push origin main
</code></pre></div>
<p><$>[note]
<strong>Note:</strong> In this example, we are working on the branch named <strong>main</strong>. Your default branch may be named something else such as <strong>master</strong>. In order to find out the name of your current branch, you can run <code>git branch</code>.
<$></p>
<h2id="step-2-creating-a-static-html-site-in-nginx">Step 2 — Creating a Static HTML Site in Nginx</h2>
<p>Now, let’s set up Nginx to serve our static site. Create a new file in <code>/etc/nginx/sites-available</code> using your text editor:</p>
<p>This <code>server</code> block instructs Nginx to listen on the standard HTTP port 80 for requests to <code>static.<^>your_domain<^></code>. When it receives a request, it tries to find a file matching that request in <code>/var/www/static.<^>your_domain<^></code>. It will first try looking for the file named (for instance, if you visit <code>static.<^>your_domain<^>/shark.jpg</code>, it will try to find <code>/var/www/static.<^>your_domain<^>/shark.jpg</code>). If that does not exist, it will append a <code>/</code> to the end of the file name to serve a directory or the file named <code>index.html</code>. Finally, if none of those work, it will serve a 404 Not Found error.</p>
<p>We also don’t want anyone accessing our <code>.git</code> directory, so the next <code>location</code> block instructs Nginx to return a 404 should someone try.</p>
<p>Now, link this file from <code>sites-available</code> to <code>sites-enabled</code>:</p>
<p>We need to create the repository for there to be anything to serve, however. Move to <code>/var/www</code> where you can create the directory for hosting the site:</p>
<p>Now that you have the directory set up, you can clone the repository into it. Rather than using SSH, which would require a key, you can use the <code>file://</code> protocol for Git. This works because Nginx is running on the same server that the repository lives on. If the repository is public, you can also use the <code>https://</code> protocol.</p>
<p>It’s important to remember to add that <code>.</code> at the end of the <code>git clone</code> command, as this tells Git to check out the repository into the current directory rather than making a new one. Now, if you type <code>ls</code>, you should see the file <code>index.html</code> from your repository, and if you visit the domain you set up, you should see your page rendered.</p>
<h2id="step-3-using-git-hooks-to-publish-changes">Step 3 — Using Git Hooks to Publish Changes</h2>
<p>Now that Nginx is serving the site from our checked out repository, we can set up the <code>post-receive</code> hook to update the site.</p>
<h3id="creating-the-hook-script">Creating the Hook Script</h3>
<p>Git hooks for Gitea live in the repository that Gitea serves from. These are located in the data directory, predictably within the <code>repositories</code> subdirectory. Move to your data directory using <code>cd</code>, then move to your repository’s <code>hooks</code> directory:</p>
<spanclass="na">drwxr-xr-x 6 git git 4096 Jun 27 17:29 ./</span><spanclass="w"></span>
<spanclass="na">drwxr-xr-x 7 git git 4096 Jun 27 17:43 ../</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 478 Jun 27 17:29 applypatch-msg.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 896 Jun 27 17:29 commit-msg.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 376 Jun 27 17:29 post-receive*</span><spanclass="w"></span>
<spanclass="na">drwxr-xr-x 2 git git 4096 Jun 27 17:29 post-receive.d/</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 189 Jun 27 17:29 post-update.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 424 Jun 27 17:29 pre-applypatch.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 1643 Jun 27 17:29 pre-commit.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 416 Jun 27 17:29 pre-merge-commit.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 1374 Jun 27 17:29 pre-push.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 4898 Jun 27 17:29 pre-rebase.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 376 Jun 27 17:29 pre-receive*</span><spanclass="w"></span>
<spanclass="na">drwxr-xr-x 2 git git 4096 Jun 27 17:29 pre-receive.d/</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 544 Jun 27 17:29 pre-receive.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 1492 Jun 27 17:29 prepare-commit-msg.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 134 Jun 27 17:29 proc-receive*</span><spanclass="w"></span>
<spanclass="na">drwxr-xr-x 2 git git 4096 Jun 27 17:29 proc-receive.d/</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 2783 Jun 27 17:29 push-to-checkout.sample*</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 356 Jun 27 17:29 update*</span><spanclass="w"></span>
<spanclass="na">drwxr-xr-x 2 git git 4096 Jun 27 17:29 update.d/</span><spanclass="w"></span>
<spanclass="na">-rwxr-xr-x 1 git git 3650 Jun 27 17:29 update.sample*</span><spanclass="w"></span>
</code></pre></div>
<p>For our purposes, we will be creating a new script within the <code>post-receive.d</code> directory. On Linux, configuration and scripts are usually stored in a directory such as <code>/etc/apt</code> or our <code>hooks</code> directory. However, if there are multiple configuration files or scripts, they may be divided up and placed in a <code>*.d</code> directory, and the service which uses them will read all of those files in list order.</p>
<p>Open a new file in <code>post-receive.d</code> for editing named <code>deploy</code>:</p>
<p>This file can be any executable script. In our case, since we’ll just be running a simple <code>git</code> command, we’ll use a Bash script. Enter the following into that file:</p>
<p>Let’s break this script down into its parts to understand what’s happening:</p>
<ul>
<li><code>#!/bin/bash</code> tells the shell to use the bash command to run the script.</li>
<li><code>set -eux</code> specifies three options: <code>e</code> means that the script will exit on a failure, <code>u</code> means that unset variables will be an error, and <code>x</code> means that it will print the commands as it executes them. These options are good practice for preventing scripts from continuing to execute when there are errors.</li>
<li>The <code>git</code> command breaks down into <code>git pull</code> which pulls new changes from the repository, while the <code>--work-tree</code> and <code>--git-dir</code> options tell Git to use the <code>.git</code> directory within the checked out branch for all of its configuration. <code>--ff-only</code> instructs <code>git pull</code> to use fast-forward reconciliation when pulling new commits.</li>
</ul>
<p>Once you’re done editing the script and have saved and closed it, use <code>chmod</code> to make the script executable:</p>
<h3id="for-gitea-running-in-docker">For Gitea Running in Docker</h3>
<p>If Gitea is running in a Docker container — if, for instance, you deployed it using the Docker Compose method in the tutorial linked above — you will need to make a few changes to make the repository accessible from within the container. First, edit the <code>docker-compose.yml</code> file and move to the <code>volumes:</code> entry. Add a new line to that list:</p>
<p>Here, we’ve changed the original URL we used to check out the branch from <code>/<^>path_to_gitea_installation<^>/repositories/sammy/static.<^>your_domain<^>.git</code> to use <code>/data/git/</code> as the path to the installation, as that is how the volume is mapped in <code>docker-compose.yml</code>. As always, be sure to use the username and repository name appropriate to your project.</p>
<h3id="testing-the-post-receive-hook">Testing the <code>post-receive</code> Hook</h3>
<p>Now, after Gitea receives a new commit and it’s written to disk, it will run this script to update the branch checked out in <code>/var/www/static.<^>your_domain<^></code>. To test this out, change the <code>index.html</code> file on your local working directory to include a congratulations message. For example, change the file so that it resembles this:</p>
<spanclass="p"><</span><spanclass="nt">p</span><spanclass="p">></span>Congratulations on setting up a <spanclass="p"><</span><spanclass="nt">code</span><spanclass="p">></span>post-receive<spanclass="p"></</span><spanclass="nt">code</span><spanclass="p">></span> hook!
<divclass="codehilite"><pre><span></span><code>git push origin main
</code></pre></div>
<p>This time, you should see some additional output from Git. Because you set the <code>-x</code> option in our deploy script, you’ll see the output of that script during the process, prefixed with <code>remote:</code>.</p>
<spanclass="na">remote: From file:///data/git/repositories/<^>username<^>/static.<^>your_domain<^></span><spanclass="w"></span>
<spanclass="na">remote: 28c52bf..95cde6f main -> origin/main</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="na">8eed10f..95cde6f main -> main</span><spanclass="w"></span>
</code></pre></div>
<p>When you visit your page in the browser, you should see your now congratulations message displayed.</p>
<h2id="conclusion">Conclusion</h2>
<p>In this tutorial, you learned how to use Git hooks in Gitea. While you used the <code>post-receive</code> hook to deploy a static website, there are many available hooks that can help you accomplish a wide variety of tasks during your Git workflow. For more information on these hooks, the Git manual has <ahref="https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks">an in-depth chapter</a> on using them.</p>
