michaelheap.com

Workspace layouts with Hammerspoon Grid

2024-01-10T15:10:39Z

Since I switched from Arch to MacOS there’s been an i3 shaped hole in my life. I’ve used apps like Divvy to approximate it, but it’s not the same.

I tried out some of the MacOS tiling window managers, but couldn’t get to grips with them. Between having to trigger things using external apps (Yabai and skhd) and having to disable system integrity protection, things just didn’t click. One of the things I loved about i3 was its simplicity.

After many years of searching, I think I’ve found a solution in Hammerspoon.

Hammerspoon?

Hammerspoon is an automation framework for MacOS that allows you to script various things using Lua.

I’ve written about Hammerspoon before, and have been using it for window management since I abandoned Divvy a couple of years ago (when I configured a dedicated hyper key on my keyboard).

I was recently browsing through Jakub’s Hammerspoon config and spotted his usage of hs.grid to configure predefined layouts.

Predefined layouts were one of my big use cases for i3, and so I went digging.

hs.grid

hs.grid splits your screen into an x by y grid. You can place windows by specifying a width/height along with an offset for the x and y values.

I have split my screen in to an 8x2 grid, with zero margin. I also have a shortcut to show the grid overlay on screen in case I want to position a single window in a non-standard layout.

lua
hs.grid.setMargins(hs.geometry.size(0,0))
hs.grid.setGrid('8x2')
hs.hotkey.bind(hyper,'g',function()
  hs.grid.show()
end)

To align a window to the grid, you call hs.grid.set and pass an instance of hs.window as the first parameter. The window is being placed on the right hand side of the screen (4 cells offset on the x-axis, 0 on the y-axis, and it covers a 4x2 space on an 8x2 grid).

lua
hs.grid.set(window, '4,0 4x2')

Automatic layouts

One of the things that I loved about Jakub’s Hammerspoon config is that he had a helper function to discover all of the windows for a certain app before reflowing windows in to the grid.

I borrowed this idea and built some convenience functions which allow you to define layouts like this:

lua
defineLayout("Writing", 1, {
	{'Bear', '0,0 2x2'},
	{'Arc', '2,0 4x2', true}
});
defineLayout("Code", 2, {
	{'Arc', '0,0 2x2'},
	{'Code - Insiders', '2,0 4x2', true},
	{'iTerm', '6,0 2x2'}
})

Now I can press hyper+1 to have Bear on the left 1/4 of the screen and Arc in the middle half. If I’m writing code, I can press hyper+2 to have VSCode in the middle taking up half of the screen, with Arc on the left and a terminal on the right.

Applications will only be positioned if they are already launched. Hammerspoon provides a hs.application.launchOrFocus() method, but I chose to implement focusIfLaunched as sometimes I don’t have all the apps open (e.g. Bear is optional when I’m writing).

Give it a go

Hammerspoon is wonderful, and I recommend giving it a go if you haven’t already tried it. My Hammerspoon config is publicly available, and whilst I’m not a power user, it saves me a ton of time every single day.

If you’ve a Hammerspoon user and have tips and tricks you want to share, I’m @mheap@hachyderm.io. I’d love to hear them!

Bonus content

I’ve recently stumbled across aerospace, which bills itself as “an i3-like tiling window manager for macOS”. I haven’t given it a go yet, but it looks promising based on the YouTube video.

Could/Should/Will/Why

2024-01-08T20:27:59Z

I had an interesting conversation with my manager this week. I’ve been working on a lot of different projects, and was a little spread thin. In one of our calls my manager asked me why I’m working on .

We sat and chatted about it, and I tried to answer the question: why am I doing these things? After hearing me out, they agreed that everything I was doing was important. Then they repeated the question, with a slightly different emphasis:

Why am I doing these things?

I didn't have a good answer. The things needed doing. No-one else was doing them. I could do them, so I took them on. But why was I the one taking them on?

A day has a finite number of hours. If I’m spending my time doing X, then Y isn’t getting done. If Y is something that only I can (or will) do, then isn’t that a better use of my time than X?

Here’s a concrete example. I had a choice to either:

Write some tutorials for one of our products using the API
Build a proof of concept Terraform provider to understand if we want to invest in the next financial year

My decision? To do both. Work on the proof of concept first, and write some tutorials between my meetings once it's done.

That’s the wrong answer.

It turns out that writing tutorials isn’t my responsibility. More than that, by writing them I’m taking away learning opportunities from others. I’m taking it away from the product manager that wants to learn to write documentation. I’m taking it away from the writer that wants to learn more about API development.

Anything I take on should meet one of the following criteria:

No-one else can do the work
It’s time sensitive, and no-one else has capacity
There’s a learning opportunity for me

Building a system

When my manager asked why I was working on these projects, I realised that I couldn’t answer. We talked about who could do the work, who should do the work, and who will do the work. This gave me a good framework for evaluating projects before starting them.

I’ve added a final column - why - to help keep a record of why the person that will take on the project is responsible.

Here’s an example with a couple of projects:

Project	Could	Should	Will	Why
Public Demos	DevRel, Sales Engineering	Sales Engineering	Sales Engineering	Demos are a core part of the SE role. If DevRel build demos, there would be duplication.
Release Demos	Product, DevRel, Product Marketing	Product Marketing	DevRel	DevRel has an engineering background to understand the features + how to get started
Splunk Tutorial	Docs, DevRel	Docs	DevRel	Docs team is at capacity with regular release documentation
VSCode Extension	DevRel, Engineering	Engineering	N/A	Project not prioritised.
Terraform Provider	DevRel, Engineering	DevRel	DevRel	This is an initial proof of concept exploration. If the idea shows potential, it's added to the Engineering roadmap.

Let’s work through the tutorials example in more detail:

A community member asked how to send logs from Kong on a VM to Splunk
DevRel couldn’t find any existing documentation to send them
DevRel the docs team if they could write a new tutorial
The docs team share that they’re already overcommitted.

At this point DevRel have three choices:

Abandon the project
Submit it in to the docs team backlog
Do it themselves

This is your classic prioritisation problem. Whichever option you choose, fill out the why column with the rationale then move on.

Has it helped?

Kind of. I still take on more projects than I should, but having an explicit will step forces me to think about why we’re taking on this specific project. It forces me to talk to other people about the project. Could their teams take on the work? Do they want to take on the work? Are there learning opportunities?

Next time you have an idea for some work that needs doing, run it through could/should/will/why to make sure that you’re the best suited person or team to complete the project.

Create an AWS RDS database

2024-01-05T15:52:09Z

I've been using RDS to provide throwaway databases for testing and wanted to work from the CLI to speed things up. The aws rds incantations were hard to find at times, so here they are for posterity.

Create a publicly accessible Postgres database:

bash
aws rds create-db-instance --db-instance-identifier demo-db --db-instance-class db.t3.micro --allocated-storage 50 --engine postgres --publicly-accessible --master-username postgres --master-user-password YOUR_PASSWORD

Show the database status and connection details:

bash
aws rds describe-db-instances | jq '.DBInstances[] | select(.DBInstanceIdentifier == "demo-db") | .DBInstanceStatus,.Endpoint'

Delete the database:

bash
aws rds delete-db-instance --db-instance-identifier demo-db --skip-final-snapshot

Create an Azure AKS Cluster

2024-01-05T15:50:50Z

I needed to test Azure AKS with the Application Gateway Ingress Controller. Thankfully, Azure makes it easy with it's az aks CLI.

Create a new Azure resource group:

bash
az group create --name mheap-test --location uksouth

Create a new AKS cluster with the Azure Application Gateway Ingress Controller enabled:

bash
az aks create --name mheap-aks-test --resource-group mheap-test --node-count 1 --network-plugin azure --enable-managed-identity --enable-addons ingress-appgw --appgw-name mheap-appgw --appgw-subnet-cidr "10.225.0.0/16" --generate-ssh-keys

Configure kubectl to connect to this cluster:

bash
az aks get-credentials --resource-group mheap-test --name mheap-aks-test

Once you've finished testing, delete the AKS cluster and resource group:

bash
az aks delete --name mheap-aks-test --resource-group mheap-test --yes
az group delete --name mheap-test --yes

Does this live in the docs or on the knowledge base?

2024-01-05T15:21:17Z

You may also be interested in my thoughts on content living on a blog vs docs

Making customers successful with a product requires three key components:

UX: If the application is intuitive, customers are successful without thinking about it.
Documentation: Practically speaking, most apps need supporting documentation to explain new concepts or provide concrete implementation instructions.
Support: Heroes that work directly with customers every day to make them successful in a 1:1 setting.

Great UX is the ideal solution, but in most companies, customers need supporting enablement content.

As the company grows, both the documentation and support teams build out their own libraries of content to make customers successful. Eventually, they’ll hit a critical mass and someone asks the inevitable question:

Does this live in the docs or on the knowledge base?

Both teams want their content to live in their own system. Support wants to use the knowledge base as it has deep integration with their ticketing system, with workflows for pulling answers from articles which aren’t always able to integrate with external docs. Docs want to use their docs-as-code platform and all the tooling that they’ve built around the written word.

Where does the content live?

Whatever you do, don't store the content in both places. The second copy goes out of sync before you even hit publish.

Instead, categorise content in two buckets:

This is generally applicable to the majority of customers using this product
This is specific to a small number of customer setups

Imagine that you have a customer issue come in and the support team resolves it. Now what? Where does the solution go?

If the answer applies to the majority of customers, then I recommend having a small KB article so that it shows up in their day to day workflow, but the KB article has a small description that then links to docs.

If the answer is specific to a small number of customers, the answer lives in the KB. The support team shares these answers on demand in response to tickets. They're also available if people search the KB specifically (or on the docs too if you have multi-site indexing).

Splitting content by audience allows you to keep your documentation focused on the 80% of customers that can be successful without human interaction. Providing an exhaustive list of failure modes makes it difficult for customers to find what they're looking for when everything is working as expected.

Examples

The above is quite abstract, so here are some examples from the docs teams that I’ve been a part of.

Vonage provides communication APIs, including SMS. Sending an SMS using the API is something that was applicable to everyone, so it had public docs. Restrictions around the sender ID (from) used are different on a per-country basis (Peru for example). Most of Vonage’s customers were in the USA where there were no restrictions, so this information lived in the knowledge base. When the USA introduced 10DLC it affected the majority of customers, so the restrictions were added to the public docs and the knowledge base.

Kong provides connectivity tools, such as API Gateways and Service Meshes. Older versions of Ubuntu don’t have a required library (zlib) installed by default and every customer using an old version of Ubuntu encounters this issue, so we document it on the installation page. Kong Mesh allows you to proxy requests to Redis, but sometimes you get a cryptic "Error: Protocol error, got "H" error. This means that you configured your MeshGatewayRoute as with a HTTP protocol rather than TCP. A small percentage of customers hit this issue, so it lives in the knowledge base.

TL;DR

If it’s applicable to > 50% of customers, put it in the public docs
If it applies to a small percentage of customers, put it in the knowledge base
Make the support team’s life easier by putting pointers to public docs in the knowledge base

Create an Amazon EKS Cluster

2023-12-20T16:44:58Z

I've been using this Terraform module to deploy test EKS clusters for the longest time, but I just learned that it's even easier when using eksctl.

Create a cluster.yaml file with the following contents. You can change the instanceType and desiredCapacity (the number of nodes) if needed:

yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: mheap-testing
  region: eu-west-2
nodeGroups:
  - name: ng-1
    instanceType: m5.large
    desiredCapacity: 1
    volumeSize: 80
    ssh:
      allow: false

Run eksctl create cluster. It takes around 4 minutes:

bash
eksctl create cluster -f cluster.yaml

Update your kubeconfig using the aws CLI:

bash
aws eks --region eu-west-2 update-kubeconfig --name mheap-testing

Now you can run all the kubectl commands that you want.

To delete the cluster when you're done:

bash
eksctl delete cluster -f cluster.yaml

How I work: Email

2023-09-09T11:06:19Z

Depending on who you ask, I’m excellent with email, or terrible with email. I don’t let it run my life, and process my (work) inbox every 2-3 days.

My review process has four steps: triage, unsubscribe, respond and prioritise.

Triage: Read all unread emails in my inbox with the search is:unread in:inbox.
If there are emails that I don’t want to receive (e.g. cold outreach) I create a filter based on the sender so that it doesn’t land in my inbox
Things that take 2 minutes to answer are responded to immediately. Otherwise they’re labelled (not starred - more on this later) for action later
Finally, I go through my labelled items and import them in to Sunsama to be scheduled alongside my other work.

The Klinger email method

I’ve been using a multiple inbox setup from Andreas Klinger for years. Having a main inbox, then separate inboxes for high/medium priority emails allowed me to keep on top of things that I needed to do.

Go and read the Klinger email method now

However, since I started using Sunsama my inbox is no longer the source of truth for what I need to do. Instead, it’s an input in to my Sunsama plan.

Pain Points

The Klinger method is great, but it isn’t perfect. I have two big complaints, and they both have to do with the use of custom stars.

The mobile gmail app only supports star/unstar, not custom stars
Sunsama only support starred/unstarred, which meant I lost my high/medium priority differentiation

To work around this issue, I created two labels: priority/high and priority/medium. I use these for my custom inboxes instead of the red and yellow bang stars from the Klinger method. This allows me to set priorities on mobile, and filter to specific priorities within Sunsama.

The real game changer for me was when I learned that you can customise label colours. Click on the three dots next to the label name in the sidebar and choose a label colour. I chose red for high priority and yellow for medium priority. The colours help these emails stand out when I’m scrolling through my inbox.

Sunsama Integration

Finally, it’s time to look at my Sunsama workflow for emails. I review emails tagged with priority/high or priority/medium on a Monday, Wednesday and Friday.

I start with priority/high and schedule work on those emails until the list is empty. Once there are no more remaining, I start working through priority/medium emails. When the email is imported in to Sunsama, the priority label is removed automatically which makes Sunsama the source of truth.

Email is one of my lowest priority task sources. I’ll always pull from Slack and GitHub before working through my email task backlog. However, everything that comes in via email does eventually need doing so pulling them in to Sunsama is important.

How I work: Sunsama

2023-09-08T16:41:16Z

I’m a big believer in Parkinson’s Law, which states that work will expand to fill its allotted time span. The work keeps coming, and no matter how well I prioritise my todo list it always seemed to be longer at the end of the day than it was at the beginning.

Thankfully in the last couple of years I’ve solved this issue using Sunsama, a tool for tracking and scheduling work across multiple systems.

Before I get started, I want to make one thing clear. This isn’t a paid post, and I don’t get anything for recommending Sunsama. I’m just a very happy user.

What is Sunsama?

Sunsama is a combined inbox for all of your different to-do systems. It sounds strange to have an inbox for your inboxes, but when work can appear in multiple different places it’s hard to keep track of. I know some people that try to make their email inbox their to-do list, but it never worked for me.

Depending on which role I’m fulfilling, my work comes from different places. If I’m being an engineer, I’m pulling from Jira (or GitHub, depending on which team I’m working with). As a manager I’m usually responding to questions in Slack or by email. If I’m collaborating with the marketing team the tasks come via Asana, and if it’s something I’ve captured myself whilst away from my desk it’s in my work project in Todoist.

Trying to keep track of everything I need to do across all of those systems is impossible. There’s no way to rank the tasks against each other and build a consolidated, prioritised list. That’s where Sunsama comes in. It allows me to pull in tasks from all of those systems and see them in a single screen.

More than that, Sunsama lets me estimate how long each will take and schedule the tasks around my meetings for the day. It’s sad to see that some days I only get around 2 hours of time to work on assigned tasks, but it’s better to know that’s the case than to plan 6 hours of tasks and be disheartened when most of them are still on my to-do list at the end of the day.

So that’s what Sunsama is for me: a consolidated inbox that allows me to schedule tasks on my calendar to keep me honest when it comes to capping my work day at 8 hours.

Integrations

Sunsama’s killer feature is its deep integration with other products. Once upon a time I spent most of my time pulling in Jira and GitHub tasks, but now it tends to be more Slack messages and emails. Here’s my integration tier list:

S Tier: Slack (easily 75%+ of my tasks), Email
A Tier: Email, Jira, Todoist
B Tier: GitHub
C Tier: Asana

Sunsama also integrates with Trello, Notion, Outlook, ClickUp and Linear but I don’t use those tools and can’t talk about how well they work.

One of the things I love about Sunsama is that you can interact with the underlying service directly in the UI. Here’s an example of how Sunsama renders a Jira ticket. It feels familiar, and allows me to see the ticket details and update the status without leaving Sunsama.

My Sunsama Workflow

Calendar Setup

Sunsama works best when you schedule your work on your calendar. I prefer to keep my planned work separate from my meetings, so I created a second calendar to use with Sunsama. This gives me the ability to see everything in the Sunsama app, but only see my committed meetings in Google Calendar.

Channels

When I first started using Sunsama I didn’t use channels. It felt like I’d spend more time categorising work than actually doing it. However, as I started to try and build blocks of focused time I found that some coarse grained categorisation was helpful.

I don’t overdo it with channels, aiming to have as few as possible. Here’s what my current list looks like:

admin
aip
apiops
devrel
docs
kic
product
review
watch

Most of the channels are teams that I actively work with (aip, apiops, devrel, docs, kic), which leaves a couple of general areas. Anything that isn’t directly attached to a team is either admin, or something I need to review or watch. I recently split out watch as I realised that video is a much bigger time commitment than reviewing a doc.

Having each item categorised by channel allows me to batch up my day and focus on specific areas for an extended period of time. Which brings us on to the daily plan.

Daily Planning

Each morning starts with a review of what needs to get done today. I’m a heavy user of “save for later” in Slack, so the first thing that I do is go through my saved items and send them to Sunsama using the Slack integration. This works really well as Sunsama attaches a link to the conversation to the item so that I can navigate back to see additional context if needed. Any items created at this point go in to the “Today” list, or in to the backlog.

Once that’s done, I run through the “Today” list and ensure that all items have a channel set. This helps a little later on when I’m scheduling my day. If it looks like I’ll have some spare capacity during the day, I’ll try to move something from the future to today and get it done earlier (but not from the backlog. That happens once per week, which I’ll explain next).

Next, I group the items by channel before pressing the “Plan” button. I try to batch up my work by area to reduce context switching, which means that I get most of my work done in the mornings and have calls in the afternoon. I add all my events to my list of tasks so that I can see how many hours I have scheduled. Today is a busy day, and I have 7h15m of work planned to complete

At this point my day is planned and I can get started. I hover over the first item in the list, press F to enter focus mode then get started.

Backlog Review

Tasks that I can’t pick up in the next day or two get sent to the Sunsama backlog. Tasks in the backlog all have a channel set to help with the review process. Initially I tried to review the backlog on a Monday morning, but I found that most of the backlog tasks weren’t getting completed during the week.

Today, I process my backlog on a Thursday when I know how well my week is going and how much time I’ll have free on Thursday/Friday. I usually only manage to get one or two tasks out of the backlog, but manage to add around 5 per week. I’m not sure how to resolve this yet, but I follow a first-in, first-out model to try and get everything processed in a reasonable time.

When I take tasks from the backlog I try to choose tasks from a specific channel. This allows me to batch process and prevents context switching as I try to wrap things up before the end of the week.

Automation

Sunsama’s killer feature is the number of integrations there are, but that’s just the start. What really makes it powerful are the automations that you can configure for each platform.

Automations change the state of your task on the remote site based on actions within Sunsama. Here are a couple of ways that I use it:

When a Jira task is completed, prompt me to update the Jira ticket status
When a Gmail task is completed, unstar and archive the email in my inbox
When a Todoist task is completed, mark it as done in Todoist

This allows me to work entirely in Sunsama whilst still keeping external systems up to date.

Focus mode

Finally, we come to focus mode. I mentioned that I press F and get started with the day above, but let’s take a deeper look at focus mode. There are two ways to enter focus mode - the “Focus” button at the top of the current day, and pressing F whilst focused on a task.

Clicking “Focus” at the top will hide all other days and the left hand sidebar in the UI. It leaves you with your list of tasks for the day and whatever integration you have open on the right (for me this is always the calendar). This is handy to see an “at a glance” view of your day but I don’t use it much.

The alternative is to press F, which hides all sidebars and tasks except the one you were focused on. It shows the task title and metadata and brings up a small task timer (which I don’t use). I like to use this view to keep me focused on a single task, and it moves on to the next one in the list when I mark it as complete.

Features I don’t use

I feel like I’ve got a pretty good Sunsama workflow, but there are features that I don’t use too. Some of the features have been added recently and I just haven’t tried them out yet, whilst others don’t seem to fit my workflow.

Weekly objectives: Sunsama allows you to set key objectives for the week and associate your tasks with objectives. This keeps you focused on the strategic work. Unfortunately a lot of my work is escalation driven, so weekly objectives don’t work for me
Auto-archive: If a task keeps rolling over from day to day, Sunsama can remove it from your to-do list and move it to an archived section. I aggressively prune my task list manually so I have no use for auto-archive.
Time tracking: In addition to estimating how much time a task will take, Sunsama allows you track how much time you spend on each task. I just forget to do this.
Automatic scheduling: Sunsama can take the tasks for a day and automatically schedule them around your meetings. If you complete a task sooner than expected, it can re-plan your day automatically. I’ve disabled this feature, as I like to be in control of my own calendar. If I finish a task early, I prefer to stand up and walk around for a while
Daily shutdown: The end of day counterpart to the daily planning process. I do a lightweight version of this where I move incomplete items to the next day, but don’t review what was shipped. I do weekly reviews using a separate process outside of Sunsama with my wider team.

At some point I’d like to be more intention with my focus and try setting weekly objectives and try out time tracking to see if I’m spending time in the right areas.

Sunsama changed my (work) life

As someone that used to try and get everything on their to-do list done in a single day (and was inevitably disappointed when I didn’t make it all the way through), Sunsama has changed my life.

I’m fortunate that all the systems I interact with day to day are supported. In a previous role they migrated from Jira Cloud to Jira Server and Sunsama became much less useful for me.

If you’re working across multiple different systems and struggling to keep track of what needs to be done, why not give Sunsama a go?

Useful links

The Sunsama team release loom videos of useful workflows. Here are the ones that I've found most useful

Pro-tips for dealing with multi-day tasks

GitHub Actions notifications in Slack

2023-09-05T09:04:52Z

I recently learned that GitHub can send you reminders on Slack at a regularly scheduled interval. What I didn’t know is that GitHub can also send you notifications on Slack in real-time when events that you’re interested in occur. In my case, that’s when a GitHub Actions build fails.

Ever since GitHub Actions launched, people have been reaching for prebuilt actions (usually Slack Notify) to send updates to Slack. It works great, but there are a couple of downsides to this approach:

You need your Slack admin to generate a webhook URL for you
Notification logic leaks in to your GitHub Actions builds
You can only notify a single channel at a time

In December 2022, GitHub launched support for GitHub Actions workflow notifications in Slack and Microsoft Teams, which allows you to configure Slack as a webhook receiver for GitHub Actions workflow notifications.

Notifications are configured on a per-channel basis using the /github subscribe command in Slack. To get started:

Invite @github to the channel you’d like to receive notifications in
Run /github subscribe owner/repo

Real World Usage

Here’s a real world example that we use to be notified about our scheduled broken links checker, which runs once per week:

bash
/github subscribe Kong/docs.konghq.com workflows:{name:"Scheduled Broken Links Checker"}

bash
✅ Subscribed to Kong/docs.konghq.com. This channel will receive notifications for
issues, pulls, commits, releases, deployments, workflows:{name:"Scheduled Broken Links Checker"}

That’s all! As you can see, you’ll get notifications for issues, pulls, commits (only on the default branch), releases and deployments by default. That’s a bit too much for me, and I unsubscribe from all of these notifications using the following:

bash
/github unsubscribe Kong/docs.konghq.com issues pulls commits releases deployments

Now the channel will only receive notifications for the named workflow:

bash
This channel will receive notifications from Kong/docs.konghq.com for:
workflows:{name:"Scheduled Broken Links Checker"}

You can filter the notifications by workflow name, the event on which the workflow is triggered, the person that triggered the workflow (useful to review your CEO’s pull requests quickly! 😉), or the branch on which the workflow is running. For a full set of documentation, see the GitHub workflow notification filters docs.

I feed these notifications in to a personal, private channel so that they don’t impact the rest of the team. I couldn’t do that as easily if we were using notify-slack directly in the pipeline.

Pull Request Notifications

Our main use case for the GitHub notifications in Slack is for workflow success/failure, but there is one other trick we use that I’d like to share.

We use labels heavily to categorise pull requests and control CI checks (including making labels required). Here are a couple of filters I use to make sure that I don’t miss anything:

/github subscribe Kong/docs.konghq.com +label:"review:tech" - Makes sure that I see any docs platform code changes
/github subscribe Kong/docs.konghq.com +label:"review:sme" - These are usually really interesting docs to read and learn from. If a topic needs SME (subject matter expert) review, there’s something for me to learn.
/github subscribe Kong/docs.konghq.com +label:"ci:manual-approve:linting" - Alert whenever the linting CI check is skipped. We have multiple manual-approve labels and I subscribe to all of them. You can see how we override workflows manually using labels in the linting workflow.

Give it a go

The GitHub Slack integration is pretty great. Whether you’re looking for GitHub Actions notifications, to be alerted when pull requests have a specific label or just to be reminded about PRs that need your review, I recommend trying them out to see what works for you.

Accessing secrets from forks safely with GitHub Actions

2023-09-04T14:05:28Z

It feels like I see someone asking “how do I let pull requests from forks access my GitHub Actions secrets?” every other day. GitHub prevents PRs from forks from accessing secrets by default so that they can’t exfiltrate secrets and use them for malicious purposes.

There are posts out there that show you how to use pull_request_target with actions/checkout to check out the HEAD ref, but this is insecure by default as it exposes all of your secrets to anyone that can raise a pull request against a repo (which is everyone on a public repo).

So, how do you get the best of both worlds? How can you safely provide secrets to forks without malicious actors stealing them?

GitHub Actions provides a triggering actor field that lets you know who ran (or re-ran) a workflow. This allows maintainers to provide access to secrets on forks once they’ve checked the changes manually and are happy that they don’t pose a security risk by re-running a job.

If you’re working in a private repo and want to enable secrets for forks, you can make them available via repo settings. This post is only relevant for public repos.

Here’s what the workflow would look like:

Alice opens a pull request from her fork
GitHub Actions runs and fails the build as she doesn’t have permissions on the repo
Bob reviews the PR and decides that there’s nothing dangerous
Bob re-runs the failed job
GitHub Actions runs and the access check passes as Bob has write access to the repo
github.event.pull_request.head.sha is checked out and points to Alice’s changes
The rest of the workflow runs successfully with access to any repository secrets

So in short:

Check permissions
Checkout code
Run tests with secrets

Check Collaborator Permissions

GitHub not trusting pull requests from forks is a proxy for “do we trust this person?”. Rather than asking the question “is the PR from a fork”, why don’t we check what permission the actor triggering the job has?

There are two ways to check permissions - author association or user permissions. Author association tells us if they have any permissions on the repository (they’ll be marked as a collaborator no matter what permissions they have). User permissions tells us exactly what permissions they have on the repository.

If you want to learn more about author associations vs user permissions see Check permissions in a GitHub Actions workflow

If you’re not sure which to choose, I recommend checking the actor’s permissions rather than relying on author association.

Author Association

The author association is available by default in the pull request event. This means that you can check permissions directly in a workflow without using the GitHub API:

yaml
- name: Check access
  if: ${{ github.event.pull_request.author_association != 'COLLABORATOR' && github.event.pull_request.author_association != 'OWNER' }}
  run: |
    echo "Event not triggered by a collaborator."
    exit 1

This step would check if the author of the PR has any access to the repo. If they do not, the workflow will exit with error code 1.

User Permission

Alternatively, you can check if the actor has specific permissions using a GitHub Action. I personally use the following action:

yaml
- name: Get User Permission
  id: checkAccess
  uses: actions-cool/check-user-permission@v2
  with:
    require: write
    username: ${{ github.triggering_actor }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Check User Permission
  if: steps.checkAccess.outputs.require-result == 'false'
  run: |
    echo "${{ github.triggering_actor }} does not have permissions on this repo."
    echo "Current permission level is ${{ steps.checkAccess.outputs.user-permission }}"
    echo "Job originally triggered by ${{ github.actor }}"
    exit 1

The action returns outputs that you can then use to determine what to do next. I check the permission in the second step above and print a debugging message before exiting with an error code of 1 to fail the build.

You might notice that I use github.triggering_actor rather than github.actor. This is what allows us to run tests from forks if the job is re-run by someone with the correct permission level.

When checking for permissions, the available levels are none, read, write and admin. Although triage and maintain are permissions in GitHub itself, they are not reflected in the API.

Check out the new code

At this point it’s safe to check out the code as the job has been triggered by someone with write access.

I mentioned earlier that using actions/checkout with github.event.pull_request.head.sha is insecure. However, as the PR has been reviewed and the workflow run has been triggered by someone with write access we can be a little more trusting.

Here’s how to check out the code from the PR in your workflow by explicitly setting a ref:

yaml
- name: Checkout code
  uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.sha }} # This is dangerous without the first access check

Run the tests

Your workflow will be different to mine at this point. If you’re testing if you’ve configured things correctly, you can set a secret named MY_SECRET to val and use the following step:

yaml
- name: Test
  run: |
    if [[ "x${{ secrets.MY_SECRET }}" == "xval" ]]; then
      echo "Access to secrets"
    else
      echo "No access to secrets"
      exit 1
    fi

Putting it all together

Taking all of the above and combining it in to a single workflow gives us the following:

yaml
name: Run tests from fork
on:
  pull_request_target:
    types: [opened, synchronize]
jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Get User Permission
        id: checkAccess
        uses: actions-cool/check-user-permission@v2
        with:
          require: write
          username: ${{ github.triggering_actor }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Check User Permission
        if: steps.checkAccess.outputs.require-result == 'false'
        run: |
          echo "${{ github.triggering_actor }} does not have permissions on this repo."
          echo "Current permission level is ${{ steps.checkAccess.outputs.user-permission }}"
          echo "Job originally triggered by ${{ github.actor }}"
          exit 1
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          ref: ${{  github.event.pull_request.head.sha }} # This is dangerous without the first access check
      - name: Run tests
        run: |
          if [[ "x${{ secrets.MY_SECRET }}" == "xval" ]]; then
            echo "Access to secrets"
          else
            echo "No access to secrets"
            exit 1
          fi

So there we have it - a mostly safe way to run workflows with access to secrets when a pull request is raised from a fork.

Why mostly safe rather than 100% safe? It relies on humans to read the pull request diff and make a good decision. We’re all human and mistakes happen. At some point a PR will get run that shouldn’t have been, and you’ll need to rotate your secrets.

I think it’s worth it. Being able to run your full suite of tests with secrets on PRs from forks is key to delivering robust software. If secrets get leaked by mistake, well, it’s always good to test your rotation procedure periodically 😁.