So. You've just discovered Sourcehut and now you're starting to move some of your projects away from
corporate greed and censorship GitHub.
And because you're hip, your Netlify-hosted static site generator is connected to your GitHub (or whatever else) repo and your keen brain quickly noticed that Netlify does not support CI integrations with Sourcehut - but that doesn't phase you.
You start furiously typing into your search engine, and voila - you found this post. Welcome.
On the otherhand, you may be beginning to get fed up with static sites, and that's okay. I've written a short post on why static site generators aren't the perfect solution to every problem.
Step 0. Why Sourcehut?
In case you've never heard of Sourcehut before, let me give you the low-down.
Sourcehut is pretty boring, and that's kind of nice. Primarily, Sourcehut is a git host, but it also allows you to run builds (similar to GitHub actions), run mailing lists, manage bug trackers (like GitHub issues), and other cool stuff.
"But Cole", I hear you cry, "I still don't understand why you want to go through the hassle". Fair.
Step 1. Move your repo
Because Sourcehut is just a git host, this step is painless. Go sign up and come back, don't worry - I'll wait.
Note: Sourcehut does not let you use repos without an SSH key, so you're going to want to set that up as well.
After that, you'll want to create a new repo, and push your code to this new remote.
Step 2. Set up your build
Congrats, you're basically halfway there.
Next, in order to deploy the site, we're going to have to make use of the Netlify CLI tool. You should add this as a dev dependency to your project.
$ npm i -D netlify-cli
Now, log into your Netlify Account and gather 2 things: an Access Token and the site's API ID. Your token can be generated in your user settings under Applications (I reccomend generating one token per site), and your site's API ID can be found by navigating to your site's settings. Copy down both of those secrets because we'll need them in the next steps.
Next, head over to your hot new Sourcehut account and create a new build secret. For the Secret, enter
ABC-123 with your generated token from earlier. Give it the Secret Type of
File, the path of
~/.buildsecrets, and mode of
644 and save that secret!
You'll want to copy and save the UUID of that secret, it will look something like
9aa0f823-0374-4796-bb20-a1111fca0fc3. Just like the Netlify Auth Token, I recommend 1 secret file per build as well, in the event that tokens get comprimised.
Back over in your project, we're going to need to run the deploy command inside our Sourcehut build, so you'll want to add the following npm script to your package.json or equivalent:
"deploy": "netlify deploy --site=$NETLIFY_SITE_ID --dir=_site --prod",
Don't worry about your
NETLIFY_SITE_ID just yet, but make sure you replace
_site with your built website directory.
In the root of your project, create a
.build.yml file - this will tell Sourcehut's builds to trigger when you push new code to this repo. I'd encourage you to read the build documentation for a better overview so that you may better tailor this file to your needs. Here's what my build file (view on Sourcehut) looks like:
# You'll want to replace this with the ID of your secret copied above
# Replace this ID with your site's API ID
- setup: |
- build: |
NODE_ENV=production npm run build
- deploy: |
npm run deploy
Now obviously your build tasks are going to look a lot different from mine - these are named arbitrarily and do what I need them to do for my usecase. There are 2 things that are important to note here.
First, you will need to
cd into your repo a the beginning of every task. Every new task logs in to the
~/ directory on start.
Second, notice the wizardry happening over in the deploy step. At the time of writing, Sourcehut's builds don't support a clean way of adding environment variables to builds, so the workaround for the time being is to wrap the excecution of our secrets file in
set commands. Shout out to evhan posting on this issue for the solution.
If everything is configured correctly, you should be able to push these changes up to the Sourcehut repo where it will run the build, and deploy your site to Netlify!
Step 3. 10-second tidy
Now that you're riding this dopamine high, it's a good time to remove your old GitHub repo and remove and previous Netlify automation you had configured.
Step 4. Sit back and think about what a huge nerd you are
You went through a non-trival amount of effort to get this working, good on you. Hopefully this was a smooth process for you.
* At the time of writing, Sourcehut is in 'alpha' which allows users to have paid features without paying. However, if you aren't a paying customer, your services will be inaccessible once Sourcehut moved out of alpha.