BLOGC-GIT-RECEIVER(1)

📦

version 0.20.1^20240602.b1ae9c9 · 3 versions

0.20.1^20240602.b1ae9c9 · fedora 43 (latest)
0.20.1 · nixos 26.05, nixpkgs unstable
0.20.1^20240602.b1ae9c9 · fedora 44

💖 BLOGC-GIT-RECEIVER 💖

okay bestie, so this is the blogc-git-receiver page from the blogc manual, and it is literally the girlboss that turns your boring old server into a whole deployment pipeline. sit down, grab a strawberry drink 🍓, we're doing this.

✨ NAME ✨

blogc-git-receiver — a simple login shell/git hook to deploy blogc websites. she's giving PaaS energy but make it tiny. 👑

🌸 SYNOPSIS 🌸

chsh -s $(command -v blogc-git-receiver) user

🦋 DESCRIPTION 🦋

so blogc-git-receiver gives you a PaaS-like way to deploy blogc(1) websites. like, no cap. when you use it as a login shell, it will accept git payloads, create bare repositories as needed, and install a hook that takes care of rebuilding the website every single time someone pushes something to the master branch. push to deploy, periodt. 💅

your git repository must provide a blogcfile(5) (only if blogc-make(1) is installed, iykyk), or a Makefile (or a GNUMakefile) that should accept the OUTPUT_DIR variable, and install built files into the directory pointed out by this variable. that's the contract, bestie, no negotiating.

and here's the cute part: blogc-git-receiver is part of the blogc project, but it isn't tied to blogc(1) or blogc-make(1). any repository with a Makefile that builds content and installs it to OUTPUT_DIR should work with blogc-git-receiver. it's flexible like that. 🌈

🎀 SETUP 🎀

first things first: after creating a user (blogc for the examples, because of course), change its shell to blogc-git-receiver(1):

# chsh -s $(command -v blogc-git-receiver) blogc

now go add ssh keys to /home/blogc/.ssh/authorized_keys. every key in authorized_keys will be allowed to push to the git repositories, and even create new ones. main character keys only. 💖

it is also possible to add blogc-git-receiver as a command in the authorized_keys file for each key, but this setup is slightly more tricky, as you may leak shell access to a user by mistake if you forget to add the command to a key that should not have shell access. 😭 only use this method if you don't have another option (e.g. in shared hosting environments that only provide one shell account), or if you know exactly what you are doing. fr fr.

also, make sure to install all the dependencies required by the websites, including a web server. blogc-git-receiver can't handle web server virtual hosts — that's just not her job, she's not doing it, and honestly? respect.

to deploy a website (e.g. the blogc example repository):

$ git clone https://github.com/blogc/blogc-example.git
$ cd blogc-example
$ git remote add blogc blogc@${SERVER_IP}:blogs/blogc-example.git
$ git push blogc master

this will deploy the example to the server, creating a symlink to the built content in /home/blogc/repos/blogs/blogc-example.git/htdocs. ✨ this symlink should be used as the document root for the web server virtual host. if this symlink can't be read by your webserver for some reason, you can create it in some other directory by adding the full symlink path to the ~/blogc-git-receiver.ini configuration file:

$ $EDITOR ~/blogc-git-receiver.ini
[repo:blogs/blogc-example.git]
symlink=/path/to/my/symlink

do not duplicate the section if it already exists, just append the symlink path to it. bestie I'm begging you. 🙈

🔧 Rebuild last successful build 🔧

if for some reason you want to rebuild the last successful build of a given website, you can run its pre-receive hook manually in the server:

# su -s /bin/sh - blogc
$ cd ~/repos/blogs/blogc-example.git
$ ./hooks/pre-receive

this should re-run the last build as if it was pushed to git. it's like a little replay button for your deploy. ⭐

🐧 Setup with SELinux enabled (Fedora) 🐧

supposing the usage of nginx as webserver, running as the nginx user:

# dnf install -y nginx policycoreutils-python-utils
# useradd -m -s $(command -v blogc-git-receiver) blogc
# gpasswd -a nginx blogc
# chmod -R g+rx /home/blogc
# su -c "mkdir /home/blogc/{builds,repos}" -s /bin/sh blogc
# semanage fcontext -a -t httpd_sys_content_t "/home/blogc/(builds|repos)(/.*)?"
# restorecon -R -v /home/blogc
# systemctl restart nginx

after running these commands, the machine is ready to be used. slay, honestly. 🔥

💜 REPOSITORY MIRRORING 💜

users can rely on blogc-git-receiver to mirror repositories to a remote Git repository (e.g. a free Bitbucket private repository). yes, she does backups too. she does everything. 👑

please note that the blogc user must be able to push to the remote repository, and that any content manually pushed to the remote repository is overwritten by blogc-git-receiver. so like... don't do that. 💀

some reasonable ways to allow the blogc user to push to the remote repository are:

create a password-less SSH key. the key must be password-less, because the push is automatic, and remote git hooks can't be interactive. no time for you to type a passphrase, she's busy. 🏃♀️
create an oauth token in the hosting service (if it supports oauth authentication in git, e.g. GitHub) and add it to the git URL.

the mirroring feature won't block a git push, it will just raise warnings. that means that if an error happens when mirroring the repository, the deploy will still succeed. so users should pay attention to the git hook logs, to avoid losing data due to repositories not being mirrored. 👀 do not ignore the logs, bestie, they're telling you something.

this feature just requires adding a remote called mirror to the bare repository in the server, or creating a configuration file (~/blogc-git-receiver.ini), that is a simple INI-style file where each repository is represented by a section and the value of the mirror variable is the URL that should be used to push.

edit configuration file (recommended, do not duplicate the section if it already exists, just append the mirror to it):

# su -s /bin/sh - blogc
$ $EDITOR ~/blogc-git-receiver.ini
[repo:myblog.git]
mirror=$YOUR_GIT_MIRROR_URL

or, to add the mirror remote:

# su -s /bin/sh - blogc
$ cd repos
$ git init --bare myblog.git  # if not created yet
$ cd myblog.git
$ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL

both examples assume that your repository is named myblog.git. 🫶

🔐 Caveats of repository mirroring with SSH 🔐

the authentication must be done with a password-less SSH key created by the blogc user.

as the git push --mirror call is automated, users must disable SSH strict host checking in SSH's ~/.ssh/config file:

Host bitbucket.org
    StrictHostKeyChecking no

the example uses bitbucket.org as remote host, that should be changed if needed.

to change this file, users must login with /bin/sh or any other "real" shell, as root:

# su -s /bin/sh - blogc

📤 Push to mirror manually 📤

if for some reason you want to push the repository of a given website to a remote mirror, you can run its post-receive hook manually in the server:

# su -s /bin/sh - blogc
$ cd ~/repos/blogs/blogc-example.git
$ ./hooks/post-receive

WARNING: if you push manually and your server's repository is empty, you'll clean your mirror repository. 😭 like, gone. deleted. not the vibe. please be careful.

🌈 ENVIRONMENT 🌈

the following variables can be set in the SSH Server (usually in ~/.ssh/environment) to change blogc-git-receiver behaviour:

BLOGC_GIT_RECEIVER_BASE_DIR — path to the base directory that should be used by blogc-git-receiver. defaults to user's home directory. useful for shared hosting environments that only provide one shell user.
BLOGC_GIT_RECEIVER_BUILDS_DIR — path to the directory that should be used to store the blogc builds. defaults to $BLOGC_GIT_RECEIVER_BASE_DIR/builds. this directory must be readable by your webserver. this variable is useful to keep your git repositories unreadable, while letting your webserver access the built files. in this case, users need to also define custom symlinks for every repository in $BLOGC_GIT_RECEIVER_BASE_DIR/blogc-git-receiver.ini, because the default htdocs symlink inside the git repositories won't be accessible by the webserver. 🧚

the following variable is exported by blogc-git-receiver when building websites with make(1):

BLOGC_GIT_RECEIVER=1 — this variable can be used to enable building of content that should only be built when running in production environment, for example. this variable will not be exported when using blogc-make(1), whose builds are always considered to be "production" (blogc-make(1) is never called with -D).

💀 BUGS 💀

please report any issues to: https://github.com/blogc/blogc

(do it. she wants to be better. growth mindset era.) 🌱

👑 AUTHOR 👑

Rafael G. Martins <rafael@rafaelmartins.eng.br>

🌟 SEE ALSO 🌟

blogc(1), git(1), git-shell(1), chsh(1), su(1), make(1)

and that's the whole page, bestie!! 💖 this one was written by Rafael G. Martins, dated January 2025, and it lives in the blogc manual. go deploy something iconic. 🎀✨

📦 where this page comes from

fedora 43: blogc-git-receiver 0.20.1^20240602.b1ae9c9-1.fc42 · BSD-3-Clause AND MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms