Forem: Doug Tangren

digitally unmastered: the GitHub cli edition

Doug Tangren — Sun, 28 Jun 2020 03:28:36 +0000

Names have power.
- Rick Riordan, The Lightning Thief

prelude
motivation
GitHub at your command line
branching out
takeaway

prelude

There have been quite a lot of posts on the topic of renaming your default git branch from "master" to anything else recently ¹ ² ³.

Many have covered how to manage doing so on the command line. Most or which have covered how to manage propagating that rename to GitHub though its web UI.

This post covers how to close that gap with the ✨ GitHub CLI✨.

motivation

I won't attempt to convince you to change your default git branch name based on its etymology, but I will suggest that you do so for a pragmatic and practical reason.

A common argument I've seen behind those avoiding changing default branch names so far is fear of what will break in doing so. This is typically anchored to a gap in understanding of what within your system depends on it. I invite you embrace a little bit of chaos in exchange for a better understanding of your software systems. A good measure of system health is that is safe to change. When it is not, there's often an underlying issue worth exploring. In any scenario, you will walk away with more confidence in knowing how your system works.

GitHub at your command line

The GitHub CLI, gh, is GitHub's now officially supported command line interface.

On MacOS, you can install it with brew install github/gh/gh or your package manager of choice on other platforms.

The GitHub CLI comes bundled with a handful of helpful commands for interfacing with your GitHub repositories.

$ gh
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  issue:      Create and view issues
  pr:         Create, view, and checkout pull requests
  repo:       Create, clone, fork, and view repositories

ADDITIONAL COMMANDS
  alias:      Create shortcuts for gh commands
  api:        Make an authenticated GitHub API request
  completion: Generate shell completion scripts
  config:     Manage configuration for gh

What makes this CLI especially convenient is that it's git repo-aware. That means when you use gh on the command line within a git repository hosted on GitHub, the CLI is able to infer a GitHub repo context for you.

I leverage this often when I want to open the current git repo inside GitHub within a browser window.

$ gh repo view -w

branching out

With it's recent v0.10.0 release the CLI gained a few new interesting features that add open a lot of new opportunities.

gh now exposes direct client interface for the GitHub REST and GraphQL APIs so anything thing you can do with the GitHub API, you can now technically do from the gh CLI. 🤯

$ gh api graphql -F owner=':owner' -F name=':repo' -f query='
      query($name: String!, $owner: String!) {
              repository(owner: $owner, name: $name) {
                      releases(last: 3) {
                              nodes { tagName }
                      }
              }
      }
'

It won't take long before typing all of this out each time loses its novelty as you'll like have to keep digging through the GitHub API docs to remember out how to compose these requests.

Fortunately, this release also added support for custom aliases which allow you to assign a name to an optionally parameterized command template and since API requests now supported commands, you can template aliased API requests.

$ gh alias set your-alias-name 'gh-subcommand arg1 arg2 argN'

The release of this version happened around the same time as folks were catching onto the git branch rename wave, including me

Doug Tangren 🐑

@softprops

🙌 to those posting about how to digitally remaster or should I say "un-master" your default git branches.

Here's my small contribution. The #github cli folks just made it easy to alias api commands. Here's one for changing your repos default branch from the cli

20:07 PM - 13 Jun 2020

I created a local alias to reset my GitHub repository's default branches

$ gh alias \
  set default-branch \
  'api -X PATCH repos/:owner/:repo --raw-field default_branch=$1'

Now you can just do the following when you're migrating a repository.

$ gh default-branch main

But I learned there's a problematic catch with this. Any open pull requests based on your old default branch will not automatically be updated.

I recently learned through another tweet from a GitHub employee that you can reset the base branch your open prs to this newly set default branch as well.

Mislav Marohnić

@mislav

We just released GitHub CLI v0.10 yesterday and here's how easy it is to use it to rename the default branch of the repository and update all its open pull requests gist.github.com/mislav/5ac6953…

15:22 PM - 12 Jun 2020

for num in `gh pr list -B master -L999 | cut -f1`; do
  gh api \
    -XPATCH \
    "repos/:owner/:repo/pulls/${num}" \
    -f base="$newbranch" >/dev/null
  echo -n .
done

takeaway

Even if you are on the market for changing your git branches, its useful to try to learn what dependencies you don't know you have on your branches yet.

It's also worth exploring the GitHub CLI for other use cases. You can technically do anything with GitHub from the command line now.

thoughts on GitHub design updates?

Doug Tangren — Wed, 24 Jun 2020 05:09:34 +0000

I was curious what folks think about GitHub's design update rollout

https://github.blog/changelog/2020-06-23-design-updates-to-repositories-and-github-ui/

Better/worse?

I'm a fan of the mobile improvements having spent a considerable amount of time reading code on a phone.

I'm also a fan of surfacing releases on repo pages. I've long wanted a Releases tab in the old UI.

A dark mode would have been nice.

What do y'all think?

portable posting with devtogo

Doug Tangren — Tue, 23 Jun 2020 05:39:21 +0000

portability should be the default.
- Larry Wall

serving dev to go
dev delivery service
takeaways

In the last post, I touched a bit on the writing flow I'm iterating towards, one with an eye towards content portability and an offline focus. In this post I wanted to talk a bit more about the details of how I intend to make that actually work.

To recap, the workflow I want is

1) write content offline, locally
2) track that in a GitHub repo
3) on branch pushes, publish to dev.to and possibly a personal site where I can scratch some design idea itches

My goal is to set myself up to build up a consistent writing routine. Posting to dev.to helps hold me accountable so my first stop was checking that box.

serving dev to go

👩🏽‍💻🎒Introducing devtogo! Devtogo is a small Rust command line app that communicates with the dev.to API and synchronizes local content with a dev.to account.

⭐You can learn more about the dev.to API here.

Here's how it works.

To have any meaningful interaction with with the dev.to API, you first need an API key. You can create these on your dev.to account page. Just provide a project name to refer to the key by and click "Generate API Key". I called mine "devtogo". Call yours whatever.

Next, I get a list of all of my dev.to articles. I need this list to compare with what I content I have locally to avoid creating duplicate posts. I use the User's all articles API to fetch this list.

This is made simple and easy with the serde and reqwest crates.

⭐A crate is unit of distribution in Rust, similar to a package if you are familiar with npm or jar if you are familiar with java.

Serde makes it easy to derive a deserialization scheme for a plain old Rustlang struct at compile time.

#[derive(Debug, Deserialize)]
struct Article {
    // other fields...
    body_markdown: String,
}

Reqwest makes it easy and ergonomic to make HTTP requests that can be deserialized from a JSON response.

async fn fetch(
    client: &Client,
    api_key: &str,
) -> anyhow::Result<Vec<Article>> {
    Ok(
      client
        .get(
          "https://dev.to/api/articles/me/all?per_page=1000"
        )
        .header(
          "api-key", api_key
        )
        .send()
        .await?
        .json()
        .await?
    )
}

The field of interest is an article's body_markdown which has all of the information needed to make this work. Dev.to provides a useful page documenting what goes into this markdown document here. All posts require a title. A title makes an article unique.

With a list of articles on hand, devtogo collects a list of local markdown files from a local directory and parses out article titles from their front matter, validating some basic correctness rules. Front matter in this context is just structured meta data embedded within your markdown file.

If a local article exists with a title that already exists it calls the update article API other wise it creates a new article with the create article API.

dev delivery service

I'd like for uploading articles to be based on pushes to a GitHub repository.

GitHub Actions fits this need like a glove. GitHub Actions is a declarative workflow automation tool built directly into GitHub. If you aren't using Actions by now, you are actively losing out value you get for free when using GitHub!

So how do I make this work? To react to a repository event like a push you simply need to drop a yaml file into directory named .github/workflows telling GitHub what to do when a push happens. You can call this file anything. I tend to call this main.yml when it's the main workflow for my repository. Below is a full example.

name: Main

on: push

jobs:
  publish-devto:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup devtogo
        run: |
          mkdir -p $GITHUB_WORKSPACE/bin
          export VERSION=v0.1.0
          curl -L "https://github.com/softprops/devtogo/releases/download/${VERSION}/devtogo-$(uname -s)-$(uname -m).tar.gz" \
            | tar -xz -C $GITHUB_WORKSPACE/bin
          $GITHUB_WORKSPACE/bin/devtogo --version
          echo "::add-path::$GITHUB_WORKSPACE/bin"
      - name: Publish
        run: devtogo -s posts
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

Let's break this down, bit by bit.

This first line gives the workflow a name used for display in the actions UI, In your repository, this lives under the "actions" tab.

name: Main

The second line tells GitHub what repository event to react to for this workflow. In this case, push events.

on: push

The next lines declare a list of "jobs" to execute when a push happens. These can be arbitrary and run parallel or can be ordered by dependencies on one another and run sequentially. Here I'm only declaring a single job called "publish-devto".

jobs:
  publish-devto:
    ...

The next line tells GitHub what kind of virtualized environment to run on. I tend to default to ubuntu-latest, but you can also run workflows on macos and windows if you'd like.

jobs:
  publish-devto:
+    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup devtogo
        run: |
          mkdir -p $GITHUB_WORKSPACE/bin
          export VERSION=v0.1.0
          curl -L "https://github.com/softprops/devtogo/releases/download/${VERSION}/devtogo-$(uname -s)-$(uname -m).tar.gz" \
            | tar -xz -C $GITHUB_WORKSPACE/bin
          $GITHUB_WORKSPACE/bin/devtogo --version
          echo "::add-path::$GITHUB_WORKSPACE/bin"
      - name: Publish
        run: devtogo -s posts
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

The next lines starts list out the sequential steps performed in a job. The first step of my workflow tells GitHub Actions to checkout the latest source code for my branch. I'll need this to get the latest content to publish.

jobs:
  publish-devto:
    runs-on: ubuntu-latest
    steps:
+     - name: Checkout
+       uses: actions/checkout@v2
      - name: Setup devtogo
        run: |
          mkdir -p $GITHUB_WORKSPACE/bin
          export VERSION=v0.1.0
          curl -L "https://github.com/softprops/devtogo/releases/download/${VERSION}/devtogo-$(uname -s)-$(uname -m).tar.gz" \
            | tar -xz -C $GITHUB_WORKSPACE/bin
          $GITHUB_WORKSPACE/bin/devtogo --version
          echo "::add-path::$GITHUB_WORKSPACE/bin"
      - name: Publish
        run: devtogo -s posts
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

The next step installs the devtogo tool from a GitHub release asset and adds it to the jobs PATH.

jobs:
  publish-devto:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
+     - name: Setup devtogo
+       run: |
+         mkdir -p $GITHUB_WORKSPACE/bin
+         export VERSION=v0.1.0
+         curl -L "https://github.com/softprops/devtogo/releases/download/${VERSION}/devtogo-$(uname -s)-$(uname -m).tar.gz" \
+           | tar -xz -C $GITHUB_WORKSPACE/bin
+         $GITHUB_WORKSPACE/bin/devtogo --version
+         echo "::add-path::$GITHUB_WORKSPACE/bin"
      - name: Publish
        run: devtogo -s posts
        env:
          DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

The last step runs to tool and performs the upload outlined above.

Note the DEVTO_API_KEY environment variable. The tool expects this to exist and contain a valid dev.io API key. These are considered secret, don't store these in code or share with others! Instead you can safely and securely store them inside your repository's encrypted Secrets. The example below shows how you can dereference a secret and store it in a workflow steps environment. These steps are ephemeral. All other parts of your workflow will not have access to this secret.

jobs:
  publish-devto:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup devtogo
        run: |
          mkdir -p $GITHUB_WORKSPACE/bin
          export VERSION=v0.1.0
          curl -L "https://github.com/softprops/devtogo/releases/download/${VERSION}/devtogo-$(uname -s)-$(uname -m).tar.gz" \
          $GITHUB_WORKSPACE/bin/devtogo --version
          echo "::add-path::$GITHUB_WORKSPACE/bin"
+     - name: Publish
+       run: devtogo -s posts
+       env:
+         DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}

That's it for today. In a future post I'll likely post about experimenting with static site generators. Stay tuned.

takeaways

dev.to api is really straight forward and makes the platform that much more compelling to use.
If you're into the idea of portable content, give devtogo a whirl. I'm interested in your feedback.

If you are just interesting in experimenting locally you can also install the tool with homebrew

  $ brew install softprops/tools/devtogo
  $ devtogo --help

dev together

Doug Tangren — Fri, 19 Jun 2020 04:45:04 +0000

👩🏽‍💻👩🏻‍💻👨🏽‍💻👩‍💻🧑🏿‍💻

A group needs only two things to be a tribe: a shared interest and a way to communicate.
- Seth Godin: Tribes

a goal
from the top
trying size medium
rediscovering community
principle flow
takeaway

a goal

A goal without plan is just a wish¹. I've been wishing I could write more often for a very long time. It's something I know I should put more time into. I've been thinking lately about how I could reframe that wish as a goal.

Making a routine of writing is an effective means of learning how to communicate well. Communication is idea delivery. Ideas you can't transfer well to others aren't useful despite their potential usefulness. Programming is also idea delivery but programming alone without writing is like eating unbalanced diet for if you want to get better at delivering ideas.

I haven't blogged in a while so I recently starting reflecting. Written on the first page of my junior investigator's memopad are the words: 🗒️ "Question: Why don't I write more often?"

from the top

My blogging journey started with a humble tumblr². A few to be precise³ ⁴. My goal at that time was to capture what I was learning and share it with others with some hope that others might find it useful. Simply tracking links set a relatively low bar for writing but at least it created a space for sharing random things and ideas I learned on my programmer's journey. Eventually I got distracted with tumblr's theme engine and lost focus on my goal.

I soon after felt the young developer's itch and pang of curiosity to write my own blog publishing tool. For historical context, this was during era of what I call Ruby on Rails' "golden age", back when Rails was first starting to take off. If you wanted to start a new project you were already half way done almost as soon as you started. There's still something to be said today for the virtue of being able to do that way back then, circa 2005.

As expected, my little toy posting machine ended out resembling much of what tumblr already did well and in the end, keeping the pieces of that tool in place took as much time if not more that my writing time itself. Well played past me ✋. The exercise is always more important than the artifact so I ditched the artifact and learned from the exercise. I'm glad I did. I learned the useful lesson in the cost of time spent on undifferentiated heavy weight lifting. You write it, you run it. Whose got time to run it? Oh and it's software so you have to maintain it, so...

I stopped writing for a while and reflected for a bit after about what I wanted from a writing platform.

trying size medium

At that time what I wanted was a quality, hands off writing platform. No maintenance. Fewer jazz hands. Just a platform to focus on writing. Soon afterwards I fell in with "The Medium" crowd.

The allure of medium.com when it first arrived on the scene was that it positioned itself as being the place to discover quality and thought leading writing. Not to knock on a well done and nicely designed product, but what I actually experienced in practice was a platform where nearly every poster followed roughly the same cookie cutter recipe. The content eventually felt uninspired, and as such, eventually as was I. Nothing felt original.

Medium also eventually came with an exclusivity price. I found myself inflicting more self injury as time passed stubbing my feet tripping over paywalls while trying to consume content I got push notifications about than I did absorbing new ideas. As a content creator I felt odds with the product asking me to pay for a service I was actively contributing content to.

It's a solid product but ended out not feeling like something I felt invested in. Something was missing.

So I dialed writing down to 0 for a while again.

rediscovering community

These days I mostly offer small denominations of code graphics embedded in tweets but I've found even that quickly loses its novelty. It's also not horribly accessible! What Twitter lacks is ample space to communicate context, the why, and most importantly -- what I learned. What I wanted was a place to share both long and short TIL posts.

I've recently revisited the idea of hand crafting a blog but rather than writing a tool from scratch for the joy of reinventing existing publishing mechanics, I wanted a place to explore creativity using the the often forgotten raw materials of the web: HTML, CSS and JavaScript. The HCJ stack doesn't have a cool ring to it but It will make a come back. Just you wait! I don't get to exercise those muscles enough and I feel my inner designer belly needs some situps. I didn't want to fall into a trap of maintaining a new tool. Fortunately, I don't have to and neither do you!

Around that same time I rediscovered dev.to. I'd actually already heard about dev.to much earlier but ignored it without good excuse. I now regret that. It was only by chance that I saw this tweet which caught my eye with this graphic.

This tweet reminded me of another reason I sometimes avoid writing: the internet troll patrol and the reserve natural guard of developers just waiting to be deployed when someone is wrong on the internet. I think this is currently the biggest draw of dev.to and the thing I've been missing with writing platforms: a supportive community.

What I really dig about dev.to is that the more time you spend with it, the more you'll start to notice its primarily an vibrant and supportive developer community and only secondarily a blogging platform. Posting articles is just a mechanic to that end. Community is the real product being offered. For those that know me, that's a my peanut butter and jam. The reason why I'm packing up and moving to dev.to is the community.

principle flow

After Medium, I have stronger, renewed principles on what a writing platforms ought to be. If monetizing still is your thing, dev.to has a nicer more open approach.

But there's one more thing. My writing so far hasn't really be set up to adapt to change. My writing lives inside the platforms that I've used in the past. It seems very probably that I'll continue to move around so it makes sense that I can carry my content with me where ever I go next. I'd like to be able to live more portably so that I am better equipped for future change.

Offline authoring is a direction I've also wanted. I am I fan of feeling the flow when trying to think creatively. Offline writing avoids online distractions and gives you space to think.

Here's the flow I'm currently iterating towards.

Write everything locally, offline
Store posts in a GitHub code repository
On git pushes, trigger a GitHub action that
- builds a static content site and publish that to gh pages
- run a tool to upload the same content to dev.to where I can make new friends and not have think about content discovery.

In a separate post, I'll write in more detail this setup in more detail and a little tool I wrote if you are interested in using the flow yourself.

To me, that's best of all the worlds: distraction free writing, liberated content, participating more in an open and friendly community, and creating space to explore the HCJ stack and work on my web love handles.

takeaway

It's useful reflect often.

Reflecting will give you a better sense for your principles. You'll also learn how to be happier and find what you are looking for.

What I learned is that my goal wasn't just creating routine for writing. It was finding a community to share it with.