A number of the companies I’ve been interviewing with are using Guide to create an “interview guide” that they send to candidates. I really like this. It includes information about the interview topic, interviewer profiles, and relevant links to pages on the company website and/or blog.
For one company, an interviewer profile linked to that person’s GitHub profile, so I took a look. Instead of the standard profile, they have a custom thing with lots of fun stats about their activity on GitHub. Neat!
But how do I do that? It took me an embarrassingly long time to figure out what
the GitHub feature for this was named. The docs call it “Managing your
profile
README”. Doing
it is simple. If your account name is “githubuser”, you make a new repo called
“githubuser”. Then any README.md in that repo will be displayed on your
GitHub profile page.
I think this feature has existed for a long time but I somehow managed to miss
it. I took a look at how the profile I linked to,
Eric’s, is generated. It’s using the
lowlighter/metrics GitHub
Actions. Each plugin generates an
infographic, and you control what is generated by which plugins you use in
your GitHub Actions workflow. The actual generation uses GitHub’s API (or
other services for a few plugins).
But while I like how it looks, I don’t like that it only generates images. This means that nothing is clickable, so you can’t link to recent PRs or repos with recent activity, for example.
Fortunately, there are many other options. A search for “github profile generator” finds many options. One of the most popular appears to be Rahul Jain’s. You fill out a web form and it gives you some markdown to turn into your profile.
But I don’t like this one either. The content it generates is essentially static. If you want to update it you need to go to the form and change things (though you can save your config between uses).
I wanted something that would regenerate regularly, and I wanted it to include whatever I wanted. I also wanted the output to be Markdown (without lots of images) so it could have clickable links. There was nothing else to do but to build yet another profile generator!
Does the world need another profile generator? No, it doesn’t. Did I do it anyway? Yes, I did.
You can see its output in my profile right now.
How It Works
I wrote it in Rust. Is Rust the best language for this? Yes, because I want to learn more Rust.
The code lives in the autarch/autarch repo
itself.
I started with octorust, which
uses GitHub’s REST API (the V3 API). REST
APIs are usually quite easy to understand, even though you end up with a lot
of API calls in many cases. However, at one point I found a weird bug in
octorust where the Repos::list_languages
method
inexplicably returns a Result<i64> instead of the data it should
return.
The octorust crate is entirely generated, and the generated code lives
alongside the generator in the oxidecomputer/third-party-api-clients
repo. That repo has
issues disabled, so I couldn’t report this (though it does allow PRs).
In the meantime, I’d been looking at how lowlighter/metrics was implemented
and saw that it was using GitHub’s GraphQL API (the V4
API). I find GraphQL more challenging to
use than REST since you need to formulate queries from scratch, rather than
using predefined REST endpoints that correspond to specific resources. But the
big advantage of GraphQL is that you can get exactly the data you want across
multiple resources in a single query.
I decided that this was a good opportunity to learn something new, so I took
some queries from the lowlighter/metrics repo and started massaging them to
give me what I wanted.
At first, I tried a single query to give me all the repos to which I had access via the User repositories field. But for some reason, this seemed to skip some repos in my houseabsolute organization. There’s a good chance this was user error on my part, but I eventually ended up simply doing one query for the user and one for the org.
I used the graphql_client crate to
make these requests. At first, I used its macros to generate code at compile
time from my queries. But the huge downside of this is that it doesn’t play
very nicely with code completion. The generated structs are quite complex, and
the only way for me to find out what fields they contained was to use
cargo-expand. But that didn’t
help with code completion.
Fortunately, the crate also includes a graphql-client binary that will
generate the same code that the macro does. This was much better. I could open
the code in Emacs to view the generated structs and modules, and code
completion just worked.
There was still one unfortunate issue, which is that even though my queries for user repos and org repos are nearly identical, the generator produces different Rust types for the user’s list of repos versus the org’s. This means that my stats collection code needs to be repeated for each type.
There are a couple of ways I could fix it. One would be to create a trait that each type can implement. But traits are defined in terms of methods. That means I’d have to write methods for each field in common between the types that I wanted to access. I did try this, but then I ran into lifetime issues when trying to take references to data in these structs. I’m sure those issues are solvable, but I just wanted to get a profile up, not spend all my time solving lifetime issues!
The other way to deal with this would be to write a macro of my own for the
stats collection code. But that would have the same code completion problems,
and that feels way over-engineered. I think what would be ideal would be a way
to tell the graphql-client codegen that these two types are the same
type. But that’s a PR for another day.
The final piece to make it all work is a simple GitHub Actions workflow that
runs the
generator. It
runs whenever I push to the master branch of the generator repo as well as
running nightly. If the generated README.md changes, it commits the changes
and pushes the commit to the repo.
GitHub will stop running scheduled workflows for a repo after 60 days of inactivity, but I’m fairly sure that commits made by this workflow will count as activity, so it will never stop running. But I will find out in a couple of months.
If you want to use this for your own profile you’ll have to change some of the code. I have my username and org as a constant in the code, and most people probably don’t have a single org for most of their code. But really, you should probably use one of the many more battle-tested alternatives.