Deploy to Netlify with Sourcehut

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.

For what I need, Sourcehut is: a) on feature parity with GitHub, b) run by a couple guys who are completely transparent about the financial situation of their company, c) completely open source, and d) javascript-free. They say vote with your wallet, and these guys get my vote (because Sourcehut isn't free - well, sorta*).

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 NETLIFY_AUTH_TOKEN=ABC-123, replacing 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:

image: archlinux
packages:
  - nodejs
  - npm
secrets:
  # You'll want to replace this with the ID of your secret copied above
  - 9aa0f823-0374-4796-bb20-a1111fca0fc3
environment:
  # Replace this ID with your site's API ID
  NETLIFY_SITE_ID: d5f0118c-2893-48ec-932f-27d7d078e6e4
tasks:
  - setup: |
      cd colbyhub.io
      npm i
  - build: |
      cd colbyhub.io
      NODE_ENV=production npm run build
  - deploy: |
      cd colbyhub.io
      {
        set +x
        . ~/.buildsecrets
        set -x
      }
      export NETLIFY_AUTH_TOKEN
      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.