update from sparkleup
This commit is contained in:
parent
e15c4af0ad
commit
41df1c6407
261
work/gitea-3.md
261
work/gitea-3.md
|
|
@ -1,10 +1,16 @@
|
|||
# How To Use Git Hooks with Gitea
|
||||
# How To Deploy Projects from Gitea Using Git Hooks
|
||||
|
||||
### Introduction
|
||||
|
||||
The popular source code management system [Git](https://git-scm.com) 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.
|
||||
|
||||
These actions are called **hooks**, and there are several that you can use for various steps along the way to perform additional work within your Git workflow. This tutorial will take a look at three such hooks to provide an overview of what is possible with this functionality.
|
||||
These actions are called **hooks**, and there are several that you can use for various steps along the way to perform additional work within your Git workflow. For example:
|
||||
|
||||
* `post-receive` hooks can be used to perform actions when a commit is pushed to the repository and are useful for CI/CD.
|
||||
* `post-merge` hooks can be used to perform actions after a merge has been completed and are useful for logging and notifications.
|
||||
* `post-checkout` hooks can be used to perform actions after you run `git checkout` and are useful for setting up project environments.
|
||||
|
||||
For this tutorial, we will be looking at using the `post-receive` 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
|
@ -13,6 +19,253 @@ Gitea is a lightweight and flexible source code management system that will be u
|
|||
* An Ubuntu 20.04 server with a non-root user configured with `sudo` privileges as described in the [Initial server setup for Ubuntu 20.94](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-20-04) tutorial.
|
||||
* Gitea installed on the server behind Nginx, ready to interact with using Git over SSH as described in [How To Install Gitea on Ubuntu Using Docker](https://www.digitalocean.com/community/tutorials/how-to-install-gitea-on-ubuntu-using-docker).
|
||||
|
||||
## Publishing a Static HTML Site When Commits are Received
|
||||
|
||||
### Step 1 :
|
||||
## Step 1 — Creating a Static HTML Project in Gitea
|
||||
|
||||
To begin with, you will need a repository set up in Gitea. Create a new repository using the **+** 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 **Create Repository**.
|
||||
|
||||
[](TODO)
|
||||
|
||||
For this example, we'll be using the user `sammy`'s repository `static-sammy.com`, but in your case, use your own username and repository name. Now, wherever you plan on developing, check out that repository using `git clone`:
|
||||
|
||||
```command
|
||||
git clone git@<^>your_domain<^>:sammy/static-sammy.com
|
||||
```
|
||||
|
||||
Move into that directory using `cd`:
|
||||
|
||||
```command
|
||||
cd static-sammy.com
|
||||
```
|
||||
|
||||
Now, create a file named `index.html` which will be served by Nginx. The following example uses `nano`. This file will contain a little bit of text that we can view in the browser.
|
||||
|
||||
```command
|
||||
nano index.html
|
||||
```
|
||||
|
||||
Within that file, add a snippet of HTML that you will recognize:
|
||||
|
||||
```html
|
||||
<html>
|
||||
<head>
|
||||
<title>Testing Gitea</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>It works!</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Save and close the file. If you used `nano` to edit the file, you can do so by pressing `Ctrl + X`, `Y`, and then `Enter`.
|
||||
|
||||
Now, add the file to the git working tree:
|
||||
|
||||
```command
|
||||
git add index.html
|
||||
```
|
||||
|
||||
Now that the file is added, commit your changes:
|
||||
|
||||
```command
|
||||
git commit -m "Added index.html"
|
||||
```
|
||||
|
||||
Push your changes up to your Gitea repository:
|
||||
|
||||
```command
|
||||
git push origin main
|
||||
```
|
||||
|
||||
<$>[note]
|
||||
**Note:** In this example, we are working on the branch named **main**. Your default branch may be named something else such as **master**. In order to find out the name of your current branch, you can run `git branch`.
|
||||
<$>
|
||||
|
||||
## Step 2 — Creating a Static HTML Site in Nginx
|
||||
|
||||
Now, let's set up Nginx to serve our static site. Create a new file in `/etc/nginx/sites-available` using your text editor:
|
||||
|
||||
```command
|
||||
sudo nano /etc/nginx/sites-available/static-sammy
|
||||
```
|
||||
|
||||
In this file, enter the following:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
server_name static-sammy.com;
|
||||
listen 80;
|
||||
|
||||
root /var/www/static-sammy.com;
|
||||
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ =404;
|
||||
}
|
||||
|
||||
location /.git {
|
||||
return 404;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This `server` block instructs Nginx to listen on the standard HTTP port 80 for requests to `static-sammy.com`. When it receives a request, it tries to find a file matching that request in `/var/www/static-sammy.com`. It will first try looking for the file named (for instance, if you visit `static-sammy.com/shark.jpg`, it will try to find `/var/www/static-sammy.com/shark.jpg`). If that does not exist, it will append a `/` to the end of the file name to serve a directory or the file named `index.html`. Finally, if none of those work, it will serve a 404 Not Found error.
|
||||
|
||||
We also don't want anyone accessing our `.git` directory, so the next `location` block instructs Nginx to return a 404 should someone try.
|
||||
|
||||
Now, link this file from `sites-available` to `sites-enabled`:
|
||||
|
||||
```command
|
||||
sudo ln -s /etc/nginx/sites-available/static-sammy /etc/nginx/sites-enabled/static-sammy
|
||||
```
|
||||
|
||||
In order to make sure everything looks good, you can test the new configuration:
|
||||
|
||||
```command
|
||||
sudo nginx -t
|
||||
```
|
||||
|
||||
If all has gone well, you should see something like the following:
|
||||
|
||||
```
|
||||
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
|
||||
nginx: configuration file /etc/nginx/nginx.conf test is successful
|
||||
```
|
||||
|
||||
Restarting the server will make these changes live.
|
||||
|
||||
```command
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
We need to create the repository for there to be anything to serve, however. Move to `/var/www` where you can create the directory for hosting the site:
|
||||
|
||||
```command
|
||||
cd /var/www
|
||||
```
|
||||
|
||||
Make the directory you specified in your server block above:
|
||||
|
||||
```command
|
||||
sudo mkdir static-sammy.com
|
||||
```
|
||||
|
||||
You will need to change the permissions on this directory so that both you and the `git` user have write access.
|
||||
|
||||
```command
|
||||
sudo chown <^>username<^>:git static-sammy.com
|
||||
sudo chmod g+x static-sammy.com
|
||||
```
|
||||
|
||||
Move to that directory:
|
||||
|
||||
```command
|
||||
cd static-sammy.com
|
||||
```
|
||||
|
||||
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 `file://` 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 `https://` protocol.
|
||||
|
||||
```command
|
||||
git clone file:///<^>path_to_gitea_installation<^>/repositories/sammy/static-sammy.com.git .
|
||||
```
|
||||
|
||||
It's important to remember to add that `.` at the end of the `git clone` command, as this tells Git to check out the repository into the current directory rather than making a new one. Now, if you type `ls`, you should see the file `index.html` from your repository, and if you visit the domain you set up, you should see your page rendered.
|
||||
|
||||
[](TODO)
|
||||
|
||||
## Step 3 — Using Git Hooks to Publish Changes
|
||||
|
||||
Now that Nginx is serving the site from our checked out repository, we can set up the `post-receive` hook to update the site.
|
||||
|
||||
Git hooks for Gitea live in the repository that Gitea serves from. These are located in the data directory, predictably within the `repositories` subdirectory. Move to your data directory using `cd`, then move to your repository's `hooks` directory:
|
||||
|
||||
```command
|
||||
cd git/repositories/sammy/static-sammy.com.git/hooks
|
||||
```
|
||||
|
||||
If you list the files in this directory, you will see a whole host of sample scripts, plus a few directories:
|
||||
|
||||
```
|
||||
total 92
|
||||
drwxr-xr-x 6 git git 4096 Jun 27 17:29 ./
|
||||
drwxr-xr-x 7 git git 4096 Jun 27 17:43 ../
|
||||
-rwxr-xr-x 1 git git 478 Jun 27 17:29 applypatch-msg.sample*
|
||||
-rwxr-xr-x 1 git git 896 Jun 27 17:29 commit-msg.sample*
|
||||
-rwxr-xr-x 1 git git 376 Jun 27 17:29 post-receive*
|
||||
drwxr-xr-x 2 git git 4096 Jun 27 17:29 post-receive.d/
|
||||
-rwxr-xr-x 1 git git 189 Jun 27 17:29 post-update.sample*
|
||||
-rwxr-xr-x 1 git git 424 Jun 27 17:29 pre-applypatch.sample*
|
||||
-rwxr-xr-x 1 git git 1643 Jun 27 17:29 pre-commit.sample*
|
||||
-rwxr-xr-x 1 git git 416 Jun 27 17:29 pre-merge-commit.sample*
|
||||
-rwxr-xr-x 1 git git 1374 Jun 27 17:29 pre-push.sample*
|
||||
-rwxr-xr-x 1 git git 4898 Jun 27 17:29 pre-rebase.sample*
|
||||
-rwxr-xr-x 1 git git 376 Jun 27 17:29 pre-receive*
|
||||
drwxr-xr-x 2 git git 4096 Jun 27 17:29 pre-receive.d/
|
||||
-rwxr-xr-x 1 git git 544 Jun 27 17:29 pre-receive.sample*
|
||||
-rwxr-xr-x 1 git git 1492 Jun 27 17:29 prepare-commit-msg.sample*
|
||||
-rwxr-xr-x 1 git git 134 Jun 27 17:29 proc-receive*
|
||||
drwxr-xr-x 2 git git 4096 Jun 27 17:29 proc-receive.d/
|
||||
-rwxr-xr-x 1 git git 2783 Jun 27 17:29 push-to-checkout.sample*
|
||||
-rwxr-xr-x 1 git git 356 Jun 27 17:29 update*
|
||||
drwxr-xr-x 2 git git 4096 Jun 27 17:29 update.d/
|
||||
-rwxr-xr-x 1 git git 3650 Jun 27 17:29 update.sample*
|
||||
```
|
||||
|
||||
For our purposes, we will be creating a new script within the `post-receive.d` directory. On Linux, configuration and scripts are usually stored in a directory such as `/etc/apt` or our `hooks` directory. However, if there are multiple configuration files or scripts, they may be divided up and placed in a `*.d` directory, and the service which uses them will read all of those files in list order.
|
||||
|
||||
Open a new file in `post-receive.d` for editing named `deploy`:
|
||||
|
||||
```command
|
||||
nano post-receive.d/deploy
|
||||
```
|
||||
|
||||
This file can be any executable script. In our case, since we'll just be running a simple `git` command, we'll use a Bash script. Enter the following into that file:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
set -eux
|
||||
|
||||
git --work-tree=/var/www/static-sammy.com/ --git-dir=/var/www/static-sammy.com/.git pull
|
||||
```
|
||||
|
||||
Let's break this script down into its parts to understand what's happening:
|
||||
|
||||
* `#!/bin/bash` tells the shell to use the bash command to run the script.
|
||||
* `set -eux` specifies three options: `e` means that the script will exit on a failure, `u` means that unset variables will be an error, and `x` 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.
|
||||
* The `git` command breaks down into `git pull` which pulls new changes from the repository, while the `--work-tree` and `--git-dir` options tell Git to use the `.git` directory within the checked out branch for all of its configuration.
|
||||
|
||||
Once you're done editing the script and have saved and closed it, use `chmod` to make the script executable:
|
||||
|
||||
```command
|
||||
chmod a+x post-receive.d/deploy
|
||||
```
|
||||
|
||||
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 `/var/www/static-sammy.com`. To test this out, change the `index.html` file on your local working directory to include a congratulations message. For example, change the file so that it resembles this:
|
||||
|
||||
```html
|
||||
<html>
|
||||
<head>
|
||||
<title>Testing Gitea</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>It works!</h1>
|
||||
<p>Congratulations on setting up a <code>post-receive</code> hook!
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
After saving and exiting the file, commit your changes:
|
||||
|
||||
```command
|
||||
git commit -am "Added congratulations message"
|
||||
```
|
||||
|
||||
And push your changes:
|
||||
|
||||
```command
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
|
|
|||
Loading…
Reference in New Issue