Free serverless URL shortener on Google Cloud Run

Technology keeps moving but this post has not.

What you're about to read hasn't been updated in more than a year. The information may be out of date. Let me know if you see anything that needs fixing.


I've been using with a custom domain to keep track of and share messy links for a few months now. That approach has worked very well, but it's also seriously overkill for my needs. I don't need (nor want) tracking metrics to know anything about when those links get clicked, and doesn't provide an easy way to turn that off. I was casually looking for a lighter self-hosted alternative today when I stumbled upon a serverless alternative: sheets-url-shortener. This uses Google Cloud Run to run an ultralight application container which receives an incoming web request, looks for the path in a Google Sheet, and redirects the client to the appropriate URL. It supports connecting with a custom domain, and should run happily within the Cloud Run Free Tier limits.

The Github instructions were pretty straight-forward but I did have to fumble through a few additional steps to get everything up and running. Here we go:

Shortcut mapping

Since the setup uses a simple Google Sheets document to map the shortcuts to the original long-form URLs, I started by going to to create a new Sheet. I then just copied in the shortcuts and URLs I was already using in By the way, I learned on a previous attempt that this solution only works with lowercase shortcuts so I made sure to convert my MixedCase ones as I went. Creating a new sheet

I then made a note of the Sheet ID from the URL; that's the bit that looks like 1SMeoyesCaGHRlYdGj9VyqD-qhXtab1jrcgHZ0irvNDs. That will be needed later on.

Create a new GCP project

I created a new project in my GCP account by going to and entering a descriptive name. Creating a new GCP project

Deploy to GCP

At this point, I was ready to actually kick off the deployment. Ahmet made this part exceptionally easy: just hit the Run on Google Cloud button from the Github project page. That opens up a Google Cloud Shell instance which prompts for authorization before it starts the deployment script. Open in Cloud Shell prompt

Authorize Cloud Shell prompt

The script prompted me to select a project and a region, and then asked for the Sheet ID that I copied earlier. Cloud Shell deployment

Grant access to the Sheet

In order for the Cloud Run service to be able to see the URL mappings in the Sheet I needed to share the Sheet with the service account. That service account is found by going to, clicking on the new sheets-url-shortener service, and then viewing the Permissions tab. I'm interested in the one that's Finding the service account

I then went back to the Sheet, hit the big Share button at the top, and shared the Sheet to the service account with Viewer access. Sharing to the service account

Quick test

Back in GCP land, the details page for the sheets-url-shortener Cloud Run service shows a gross-looking URL near the top: That doesn't do much for shortening my links, but it'll do just fine for a quick test. First, I pointed my browser straight to that listed URL: Testing the web server

This at least tells me that the web server portion is working. Now to see if I can redirect to my project car posts on Polywork: Testing a redirect

Hmm, not quite. Luckily the error tells me exactly what I need to do...

Enable Sheets API

I just needed to visit to enable the Google Sheets API. Enabling Sheets API

Once that's done, I can try my redirect again - and, after a brief moment, it successfully sends me on to Polywork! Successful redirect

The whole point of this project is to shorten URLs, but I haven't done that yet. I'll want to link in my domain to use that in place of the rather unwieldy I do that by going back to the Cloud Run console and selecting the option at the top to Manage Custom Domains. Manage custom domains

I can then use the Add Mapping button, select my sheets-url-shortener service, choose one of my verified domains (which I think are already verified since they're registered through Google Domains with the same account), and then specify the desired subdomain. Adding a domain mapping

The wizard then tells me exactly what record I need to create/update with my domain host: CNAME details

It took a while for the domain mapping to go live once I've updated the record. Processing mapping...

Final tests

Once it did finally update, I was able to hit to get the error/landing page, complete with a valid SSL cert: Successful error!

And testing works as well!


I'm very pleased with how this quick little project turned out. Managing my shortened links with a Google Sheet is quite convenient, and I really like the complete lack of tracking or analytics. Plus I'm a sucker for an excuse to use a cloud technology I haven't played a lot with yet.

And now I can hand out handy-dandy short links!

Link Description 1974 VW Karmann Ghia project 2014 Subaru BRZ autocross videos Chat with me on Matrix Follow me on Twitter Game with me on Stadia This post!