DEV Community: Gregor Martynus

How to (not) be a mentor to a marginalized person

Gregor Martynus — Thu, 16 Feb 2023 23:37:18 +0000

3 key lessons I took away from a 1h coaching session with Kim Crayton.

The line between mentoring and gaslighting a marginalized person is thin.

I cannot give advice on how to navigate the hierarchy of the company because I do not share the lived experience of my mentee. My white male privilege grants me safety that doesn’t require me to be constantly strategic about my interactions with others.

Example: I cannot tell a marginalized mentee to “just have an honest conversation” with their manager. There are dynamics at play that I cannot understand.

Being a mentor is like feeding a hungry person.

There is a power dynamic at play that mentors need to acknowledge. Asking for something is not the same as asking a peer.

Example: Asking my mentee for advice based on their lived experience is emotional labor. But they might agree despite their discomfort because they fear I could withhold my mentoring.

My mentee is a target for people who wish me harm.

It comes down to one of Kim’s guiding principles: prioritize the most vulnerable. I must understand and create strategy that acknowledges that when I speak out about marginalization at GitHub, I will upset people. But due to being prioritized, these people may target the most vulnerable; the very individuals I seek to protect.

Example: when I speak out about marginalization at GitHub it will upset people with power. They will go after the most vulnerable people that I care about.

I highly recommend to follow Kim on Mastodon or Twitter, and buy her new book: Profit Without Oppression on from your local or independent bookseller.

VS Code ProTip™: paste path of active file into terminal

Gregor Martynus — Fri, 21 Oct 2022 00:09:40 +0000

I need to use the path to the current active file in my VS Code editor all. The. Time!

Eventually I figured there must be a shortcut but there is none that's built-in. However, you can quickly add it yourself.

Open the command palette (Windows: Ctrl+Shift+P, Mac: Command+Shift+P)
Search for "Preferences: Open Keyboard Shortcuts (JSON)"
In the opened keybindings.json file, add a new item to the array

  {
    "key": "ctrl+shift+t",
    "command": "workbench.action.terminal.sendSequence",
    "args": { "text": "${relativeFile}" },
    "when": "terminalFocus"
  }

Now open any file, then open a terminal within VS Code, and press Ctrl+Shift+T and it will paste the full path to that file where your cursor is in the terminal.

How I created a public dashboard for the WIP GitHub App using Logflare

Gregor Martynus — Sat, 19 Dec 2020 01:04:21 +0000

The WIP app is one of the oldest and simplest GitHub apps. It blocks pull requests from being merged accidentally if someone is still working on them:

It's meant as a reference implementation for others to learn from, the source code is on GitHub, and all revenue from the marketplace subscriptions are donated.

The WIP GitHub app is continuously deployed to Vercel. Vercel has an Integrations Marketplace, which lets you easily integration with other services, e.g. for error tracking or logging. One such service is Logflare. The setup couldn't be easier:

Add the integration to your Vercel app
You will be asked to create a Logflare account
There is no 3rd step

Once setup, all logs are automatically "drained" to a "source" created in your Logflare account.

Pressing the "explore" tab in your logflare source will open Google's Data Studio with the Logflare source already setup as data source. See Logflare's guide for more details.

Note: a paid plan is required to utilize this dashboard feature.

Logflare creates the schema for your logs automatically as new logs come in, and stores the data in BigQuery, which Data Studio can use directly as a data source.

I never worked with Google Studio before, but was able to create a great interactive dashboard within an hour or so. You can see it live at https://wip.vercel.app/stats.

I am not affiliated with Logflare in any way, I'm just a big fan 😊 I cannot wait to build dashboards for all my GitHub apps now. Make sure to check it out!

Github API Authentication - Username & Password (Basic)

Gregor Martynus — Sat, 15 Feb 2020 00:11:05 +0000

Today, on February 14, 2020, GitHub announced its deprecation timeline for authenticating using a username and a password. Which means you have only time until November 13, 2020 to give this a try 🤪

I have mixed feelings about the deprecation. It makes me happy because Basic authentication has all kinds of security problems. Adding two-factor authentication made it a bit more secure, but also a pain in the 🍑

I'm sad, because I created @octokit/auth-basic to hide away most of the complexities introduced by two-factor authentication, and I think it turned out pretty nicely 😭 I think it's a good example of what an API client library can do to hide away complexities from consumers of that API.

So, for the history books, let's see how to use @octokit/auth-basic to authenticate using username, password, and two-factor authentication.

How Basic authentication works for the GitHub API

Let's try to send a request to GitHubs GET /user API using the @octokit/request package.

// my-cli.js
const { request } = require("@octokit/request");

const USERNAME = "octocat";
const PASSWORD = "secret";

request("GET /user", {
  headers: {
    authorization: `basic ${Buffer.from(`${USERNAME}:${PASSWORD}`).toString(
      "base64"
    )}`
  }
}).then(response => console.log(response.data), console.error);

Depending on your GitHub security Settings, the above code will either log the user object for your account, or it will fail with a 401 response, including a 'X-GitHub-Otp' header with the value set to required; app or required; sms.

In order to retrieve your user account, you will need to send the same request again, including a header containing the OTP.

By the way, OTP stands for one-time password. In GitHub's case, you can use the OTP more than once, because it is actually a time-based password. It usually is valid for about a minute. 🤷‍♂️

If you use an authenticator app (you should!), you already know the right OTP to send along, the request code looks like this

// my-cli.js
const { request } = require("@octokit/request");

const USERNAME = "octocat";
const PASSWORD = "secret";
const OTP = "012345";

request("GET /user", {
  headers: {
    authorization: `basic ${Buffer.from(`${USERNAME}:${PASSWORD}`).toString(
      "base64"
    )}`,
    "x-github-otp": OTP
  }
}).then(response => console.log(response.data), console.error);

If you have SMS setup for your two-factor authentication (you should not!), then you are out of luck. Not only do you not know the OTP at the time of the first request, you won't even receive an SMS with an OTP from GitHub. Why? Because only certain REST API routes trigger the SMS delivery. The OAuth Authorizations API routes, to be precise.

In order to workaround this problem, the recommend best practice is to not use basic authentication for every request. Instead, use it to create a personal access token, then use that token for the following requests.

And because you create a personal access token that you probably won't need ever again, it's a good practice to delete that token when you are done. However, the OTP you used to create the token might no longer be valid (time based, remember), so it's well possible that GitHub will respond with a 401 asking for a new OTP.

You can see, this is getting complicated pretty quick, and it's only the tip of the ice berg. For example, some requests require to be authenticated using your username and password, while for most others you can use the token. If you are curious, you can read trough the source code of @octokit/auth-basic to learn all about it. The tests will give you a pretty good summary.

🎩 `@octokit/basic-auth`

@octokit/basic-auth takes away most of the pain that is Basic Auth and two-factor authentication for GitHub's REST API. It even integrates neatly with your favorite Octokit libraries such as @octokit/rest, @octokit/core or even the super low-level @octokit/request.

In this example I'll use @octokit/basic-auth, @octokit/request and readline-sync

// my-cli.js
const { createBasicAuth } = require("@octokit/auth-basic");
const { request } = require("@octokit/request");
const { question } = require("readline-sync");

const auth = createBasicAuth({
  username: question("Username: "),
  password: question("Password: "),
  async on2Fa() {
    // prompt user for the one-time password retrieved via SMS or authenticator app
    return question("Two-factor authentication Code: ");
  }
});

const requestWithBasicAuth = request.defaults({
  request: {
    hook: auth.hook
  }
});

requestWithBasicAuth("GET /user").then(
  response => console.log(response.data),
  console.error
);

When you run the above code with Node, you will be prompted for your username and password. If you have two-factor auth setup and SMS configured for delivery, you will receive an SMS with the OTP. Once you enter the OTP the script will log the user object for your GitHub Account to your terminal.

Now lets say you need to send so many requests that the OTP becomes invalid (usually about a minute), but you still want to delete the personal access token at the end. The code would look something like this

// my-cli.js
const { createBasicAuth } = require("@octokit/auth-basic");
const { request } = require("@octokit/request");
const { question } = require("readline-sync");

run();

async function run() {
  const auth = createBasicAuth({
    username: question("Username: "),
    password: question("Password: "),
    async on2Fa() {
      // prompt user for the one-time password retrieved via SMS or authenticator app
      return question("Two-factor authentication Code: ");
    }
  });

  const requestWithBasicAuth = request.defaults({
    request: {
      hook: auth.hook
    }
  });

  const { data } = await requestWithBasicAuth("GET /user");
  console.log(`Your GitHub Account ID: ${data.id}`);

  console.log(`Sending some more requests that take a while ...`);
  const TWO_MINUTES_IN_MS = 2 * 60 * 1000;
  await new Promise(resolve => setTimeout(resolve, TWO_MINUTES_IN_MS));

  const { id } = await auth({ type: "token" });
  await requestWithBasicAuth("DELETE /authorizations/:authorization_id", {
    authorization_id: id
  });
  console.log("TOKEN deleted");
}

The code above has a two minute timeout build in to make sure the OTP becomes invalid. You will see that you will get prompted for an OTP for the 2nd time:

$ node my-cli.js
Username: gr2m
Password: ***
Two-factor authentication Code: 068194
Your GitHub Account ID: 39992
Sending some more requests that take a while ...
Two-factor authentication Code: 975808
TOKEN deleted

What are the alternatives to Basic authentication

Well, the Basic authentication party is over soon, so make sure to use alternative means of authentication before November 2020.

You can do one of two things.

Ask your users to create a personal access token and share that with you. I wrote a blog post with more details about that: GitHub API Authentication - Personal Access Tokens
Use GitHub's OAuth web application flow.

Now 2. is a nicer user experience, but it's easier said that done. Luckily, I have two blog posts lined up that will help you

OAuth: How to implement the OAuth web flow using a server and a client
CLI: How to use the OAuth web flow for CLI apps.

Stay tuned 💐

Credit

Header image: Women Code in Tech Chat CC BY 2.0

GitHub API: How to retrieve the combined pull request status from commit statuses, check runs, and GitHub Action results

Gregor Martynus — Fri, 07 Feb 2020 23:28:47 +0000

Update

At the time of the article, there was no way to retrieve the combined status for commit checks and check runs. But now there is

The final, updated code would no look like this



const QUERY = `query($owner: String!, $repo: String!, $pull_number: Int!) {
  repository(owner: $owner, name:$repo) {
    pullRequest(number:$pull_number) {
      commits(last: 1) {
        nodes {
          commit {
            statusCheckRollup {
              state
            }
          }
        }
      }
    }
  }
}`

async function getCombinedSuccess(octokit, { owner, repo, pull_number}) {
  const result = await octokit.graphql(query, { owner, repo, pull_number });
  const [{ commit: lastCommit }] = result.repository.pullRequest.commits.nodes;
  return lastCommit.statusCheckRollup.state === "SUCCESS"
}

In this post, you will learn

Where the pull request checks are coming from
There is no single API endpoint to retrieve the combined status for a pull requests
The difference between Commit Status, Check Runs, and GitHub Action results
How to get a combined status for a pull request

Storytime

I'm a big fan of automation. In order to keep all dependencies of my projects up-to-date, I use a GitHub App called Greenkeeper. It creates pull requests if there is a new version of a dependency that is out of range of what I defined in my package.json files.

This is a huge help, I could not maintain as many Open Source libraries if it was not for Greenkeeper and other automation.

However, whenever there is a new breaking version of a library that I depend on in most of my projects, I get 100s of notifications for pull requests, all of which I have to review and merge manually. After doing that a few times, I decided to create a script that can merge all pull requests from Greenkeeper that I got notifications for. I'd only need to check it once to make sure the new version is legit, all other pull requests should just be merged, as long as the pull request is green (meaning, all tests & other integrations report back with a success status).

Turns out, "as long as the pull request is green" is easier said than done.

What is a pull request status?

The first thing that is important to understand is where the list of checks shown at the bottom of most pull requests on GitHub is coming from.

Pull request checks are not set on pull requests. They are set on the last commit belonging to a pull request.

If you push another commit, all the checks will disappear from that list. The integrations that set them will need to set them again for the new commit. This is important to understand if you try to retrieve the checks using GitHub's REST or GraphQL APIs. First, you need the pull request's last commit (the "head commit"), then you can get the checks.

What is the difference between commit statuses and check runs

Commit statuses was the original way for integrators to report back a status on a commit. They were introduced in 2012. Creating a commit status is simple. Here is a code example using @octokit/request



import { request } from '@octokit/request'

// https://developer.github.com/v3/repos/statuses/#create-a-status
request('POST /repos/:owner/:repo/statuses/:commit_sha', {
  headers: {
    authorization: `token ${TOKEN}`
  },
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'abcd123',
  state: 'success',
  description: 'All tests passed',
  target_url: 'https://my-ci.com/octocat/hello-world/build/123'
})

And retrieving the combined status for a commit is as just as simple



import { request } from '@octokit/request'

// https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref
request('GET /repos/:owner/:repo/commits/:commit_sha/status', {
  headers: {
    authorization: `token ${TOKEN}`
  },
  owner: 'octocat',
  repo: 'hello-world',
  commit_sha: 'abcd123'
})
  .then(response => console.log(response.data.state))

But with the introduction of check runs in 2018, a new way was introduced to add a status to a commit, entirely separated from commit statuses. Instead of setting a target_url, check runs have a UI integrated in github.com. Integrators can set an extensive description. In many cases, they don't need to create a separate website and exclusively use the check runs UI instead.

Creating a check run is a bit more involved



import { request } from '@octokit/request'

// https://developer.github.com/v3/checks/runs/#create-a-check-run
request('POST /repos/:owner/:repo/check-runs', {
  headers: {
    authorization: `token ${TOKEN}`
  },
  owner: 'octocat',
  repo: 'hello-world',
  name: 'My CI',
  head_sha: 'abcd123', // this is the commit sha
  status: 'completed',
  conclusion: 'success',
  output: {
    title: 'All tests passed',
    summary: '123 out of 123 tests passed in 1:23 minutes',
    // more options: https://developer.github.com/v3/checks/runs/#output-object
  }
})

Unfortunately, there is no way to retrieve a combined status from all check runs, you will have to retrieve them all and go through one by one. Note that the List check runs for a specific ref endpoint does paginate, so I'd recommend using the Octokit paginate plugin



import { Octokit } from '@octokit/core'
import { paginate } from '@octokit/plugin-paginate-rest'

const MyOctokit = Octokit.plugin(paginate)
const octokit = new MyOctokit({ auth: TOKEN})

// https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref
octokit.paginate('GET /repos/:owner/:repo/commits/:ref/check-runs', (response) => response.data.conclusion)
  .then(conclusions => {
    const success = conclusions.every(conclusion => conclusion === success)
  })

A status reported by a GitHub Action is also a check run, so you will retrieve status from actions the same way.

How to retrieve the combined status for a pull request

You will have to retrieve both, the combined status of commit statuses and the combined status of check runs. Given you know the repository and the pull request number, the code would look like this using @octokit/core with the paginate plugin



async function getCombinedSuccess(octokit, { owner, repo, pull_number}) {
  // https://developer.github.com/v3/pulls/#get-a-single-pull-request
  const { data: { head: { sha: commit_sha } } } = await octokit.request('GET /repos/:owner/:repo/pulls/:pull_number', {
    owner,
    repo,
    pull_number
  })

  // https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref
  const { data: { state: commitStatusState } } = request('GET /repos/:owner/:repo/commits/:commit_sha/status', {
    owner,
    repo,
    commit_sha
  })

  // https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref
  const conclusions = await octokit.paginate('GET /repos/:owner/:repo/commits/:ref/check-runs', {
    owner,
    repo,
    commit_sha
  }, (response) => response.data.conclusion)

  const allChecksSuccess = conclusions => conclusions.every(conclusion => conclusion === success)

  return commitStatusState === 'success' && allChecksSuccess
}

Using GraphQL, you will only have to send one request. But keep in mind that octokit.graphql does not come with a solution for pagination, because it's complicated™. If you expect more than 100 check runs, you'll have to use the REST API or look into paginating the results from GraphQL (I recommend watching Rea Loretta's fantastic talk on Advanced patterns for GitHub's GraphQL API to learn how to do that, and why it's so complicated).



const QUERY = query($owner: String!, $repo: String!, $pull_number: Int!) {

  repository(owner: $owner, name:$repo) {

    pullRequest(number:$pull_number) {

      commits(last: 1) {

        nodes {

          commit {

            checkSuites(first: 100) {

              nodes {

                checkRuns(first: 100) {

                  nodes {

                    name

                    conclusion

                    permalink

                  }

                }

              }

            }

            status {

              state

              contexts {

                state

                targetUrl

                description

                context

              }

            }

          }

        }

      }

    }

  }

}

async function getCombinedSuccess(octokit, { owner, repo, pull_number}) {

  const result = await octokit.graphql(query, { owner, repo, pull_number });

  const [{ commit: lastCommit }] = result.repository.pullRequest.commits.nodes;

const allChecksSuccess = [].concat(

    ...lastCommit.checkSuites.nodes.map(node => node.checkRuns.nodes)

  ).every(checkRun => checkRun.conclusion === "SUCCESS")

  const allStatusesSuccess = lastCommit.status.contexts.every(status => status.state === "SUCCESS");

return allStatusesSuccess || allChecksSuccess

}

See it in action

I use the GraphQL version in my script to merge all open pull requests by Greenkeeper that I have unread notifications for: merge-greenkeeper-prs.

Happy automated pull request status checking & merging 🥳

Credit

The header image is by WOCinTech Chat, licensed under CC BY-SA 2.0

GitHub API Authentication - GitHub Actions

Gregor Martynus — Fri, 17 Jan 2020 21:26:12 +0000

In this post, I will explain how to create a GitHub Action workflow that adds a comment to every new pull request using

A GitHub Action workflow file (.github/workflows/pr-comment.yml)
A single JavaScript file (.github/actions/pr-comment.js)

Both files live in the same repository where the comments will be added. If you get stuck at any point, here is my repository with all the code described in this post.

Prerequisites

Install git and Node.js
Create a repository on GitHub
Clone the repository to your local machine.

Passing the `GITHUB_TOKEN` secret to a JavaScript file

GitHub Actions come with their own special token that must be passed to each workflow step explicitly: secrets.GITHUB_TOKEN. Unlike Personal Access Tokens that I explained in the previous post of this series, you don't have to manually create them. A unique GITHUB_TOKEN is created each time your GitHub Action is run.

Let's start out by creating a new workflow file at .github/workflows/pr-comment.yml

name: PR Comment
on:
  # Run this workflow only when a new pull request is opened
  # compare: https://git.io/JvTyV
  pull_request:
    types: [opened]

jobs:
  pr_comment:
    runs-on: ubuntu-latest

    steps:
      # Make files accessible to actions
      # https://github.com/actions/checkout#readme
      - uses: actions/checkout@v2
      # Install Node
      # https://github.com/actions/setup-node#readme
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      # Install dependencies
      - run: npm ci
      # Run pr-comment.js with Node and pass the authentication token 
      - run: node .github/actions/pr-comment.js
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Next, we need to create a package.json file and install a few dependencies, and create the .github/actions/pr-comment.js.

Creating a comment using JavaScript

We will use GitHub's Create a comment REST API endpoint to create the comment on every new pull request. A GraphQL query would work just the same, using octokit.graphql instead of octokit.request.

Create a package.json file in the folder you cloned your repository into:

npm init

After that, install @octokit/action

npm install @octokit/action

Next, create the .github/actions/pr-comment.js file

// GITHUB_EVENT_PATH always exists when run by an Action,
// see https://git.io/JvUf7 for a full list
const eventPayload = require(process.env.GITHUB_EVENT_PATH);
const { Octokit } = require("@octokit/action");

createPrComment();

async function createPrComment() {
  // No need to pass process.env.GITHUB_TOKEN, `@octokit/action`
  // is using it directly and throws an error if it is not present.
  const octokit = new Octokit();

  // See https://developer.github.com/v3/issues/comments/#create-a-comment
  const { data } = await octokit.request(
    "POST /repos/:repository/issues/:pr_number/comments",
    {
      repository: process.env.GITHUB_REPOSITORY,
      pr_number: eventPayload.pull_request.number,
      body: "Thank you for your pull request!"
    }
  );

  console.log("Comment created: %d", data.html_url);
}

Commit and push your changes

git add .
git commit -m 'add GitHub Action workflow to comment on new PRs'
git push origin master

Now create a new pull request on your repository. After a short delay, the Action will show up in the list of checks as pending

If all goes as expected, the action will add the new comment

Congratulations 👏 Now that you know how to send authenticated requests against GitHub's APIs with Actions and JavaScript, sky is the limit 🚀

Secrets and pull requests from forks

Creating the comment will not work when someone creates a pull request from a fork. The GITHUB_TOKEN secret is still passed, but has only read permissions, it cannot create or update anything. If that was not the case, anyone could create a pull request changing the code of the pr-comment.js script to do something malicious with your repository.

For now, I you can prevent the action from running altogether if the pull request comes from a fork by adding an if statement

# ...

jobs:
  pr_comment:
    runs-on: ubuntu-latest
    if: eventPayload.pull_request.head.repo.fork == false
    steps:
      # ...

Another alternative is to use GitHub Apps instead, which I will cover in my next blog post 😇

GitHub API Authentication - Personal Access Tokens

Gregor Martynus — Fri, 10 Jan 2020 23:44:53 +0000

Personal Access Tokens are the easiest way to authenticate requests as a GitHub user. You can create a new Personal Access Token at https://github.com/settings/tokens/new.

Set the note to something memorable. The scopes are pretty self-explanatory, only select what you are sure you will need. The public_repo scope is what you'll need in most cases, e.g. to retrieve, create or update all things related to repositories.

The next screen will show you the token. Make sure to copy it somewhere safe as it won't be shown again.

You can now use that token, for example to retrieve the latest release of octokit/core.js using curl from your terminal



curl --header "Authorization: token d64761df071c2bf517ceb063b279432ed2f89c62" \
     https://api.github.com/repos/octokit/core.js/releases/latest

Or using fetch in a browser or node-fetch in Node.js



const response = await fetch(
  "https://api.github.com/repos/octokit/core.js/releases/latest", 
  {
    headers: {
      authorization: "token d64761df071c2bf517ceb063b279432ed2f89c62"
    }
  }
)
console.log(await response.json());

Using the JavaScript Octokit

Authenticating using a personal access token is straight forward, so it's already built into https://github.com/octokit/core.js and all libraries that are built upon it.

Sending the above request would look like this in the browser



<script type="module">
import { Octokit } from "https://cdn.pika.dev/@octokit/core";

const octokit = new Octokit({ auth: "d64761df071c2bf517ceb063b279432ed2f89c62" });
octokit.request('GET /repos/:owner/:repo/releases/latest', {
  owner: "octokit",
  repo: "core.js"
}).then(response => console.log(response.data))
</script>

And like this in Node.js



const { Octokit } = require('@octokit/rest')
const octokit = new Octokit({ auth: "d64761df071c2bf517ceb063b279432ed2f89c62" });
octokit.request('GET /repos/:owner/:repo/releases/latest', {
  owner: "octokit",
  repo: "core.js"
}).then(response => console.log(response.data))

Handling errors

If the token is invalid, the server will respond with a 401 status and a "bad credentials" message



curl --header "Authorization: token invalid" https://api.github.com/notifications                                 
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.github.com/v3"
}

If the token does not have the required scopes, the server will respond with a 403 status and an explanatory message



curl --header "Authorization: token d64761df071c2bf517ceb063b279432ed2f89c62" https://api.github.com/notifications
{
  "message": "Missing the 'notifications' scope.",
  "documentation_url": "https://developer.github.com/v3/activity/notifications/#list-your-notifications"
}

New scopes cannot be added to existing tokens, you will have to create a new token with the required scopes selected to address 403 errors.

Limitations

Personal Access Tokens work great for personal usage. But if you plan to create a service or a CLI application that integrate with GitHub, there are better options that don't require the user to manually create and maintain tokens. I will write about all of them in the remaining posts of this series.

Personal Access Tokens can be used in GitHub Actions if you want the script to act as your user account. Next week I'll talk about authenticating scripts run by GitHub Actions, and how to utilize the special GITHUB_TOKEN secret as a simpler alternative to using Personal Access Tokens for most cases.

GitHub API Authentication - Introduction

Gregor Martynus — Fri, 10 Jan 2020 23:44:44 +0000

This is the first post of a series about different Authentication strategies for GitHub's APIs. The different strategies that I plan to write about are

Personal Access Tokens
GitHub Actions
Username & Password (Basic)
OAuth
Webhooks
GitHub Apps
CLI

Authenticating requests is required for GitHub's GraphQL API and strongly encouraged for GitHub's REST API.

While it is possible to send unauthenticated REST API requests, only 60 requests per hour are permitted. Unauthenticated requests are rate limited based on IP addresses, so if you sent them from virtual servers such as most CI environments they are likely depleted most of the time.

Example

Sending an anonymous request responds with X-RateLimit-* headers stating that less than 60 more requests can be sent until the rate limit is reset. For this example, I'm using curl

curl --head https://api.github.com/repos/octokit/core.js/releases/latest
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1578690442

Sending the same request with an authorization header shows the increased rate limit

curl --head \
     --header "Authorization: token 70e98949b567d678f62ed81866a1cd54aaeee400" \
     https://api.github.com/repos/octokit/core.js/releases/latest
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1578690903

The string 70e98949b567d678f62ed81866a1cd54aaeee400 is an example of a personal access token, which I wrote about in the next post of this series.

Schedule GitHub Pull Request merges using Actions

Gregor Martynus — Fri, 03 Jan 2020 21:14:55 +0000

There is currently no built-in feature to schedule a pull request merge on GitHub. But a little GitHub Action magic can fill in this gap.

In this post, I'll explain

How to set pull request status to "pending" and
How to run a script on a schedule using GitHub Actions.

If you want to explore the final code, check out the Schedule Action on GitHub.

How it works

In order to merge a pull request on a specified future date, you need two things

Set the date for the merge
Do the actual merge on the specified date

For the first step, the action will look for a string in the pull request description that looks like this

/schedule 2020-02-20

If it exists, it creates a pending status with an explanatory description.

The 2nd step is a script that runs on a special schedule event. It will look for the string above in all open pull requests. If it finds any, it will merge the pull requests that are scheduled to be merged today.

Set the date for the merge

The workflow file for the first step will look like this, you can create it as .github/workflows/schedule-merge.yml, the file name does not matter, only the directory.

name: Schedule Merge
on:
  pull_request:
    types:
      - opened
      - edited
jobs:
  schedule:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: "npm ci"
      - run: "node ./.github/actions/schedule-merge.js"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The workflow is triggered each time a pull request is created or edited (such as a description update). Then it checks out the source code of your repository, it sets up Node and installs your dependencies as defined in ./package.json. Then it runs the ./.github/actions/schedule.js file that we still need to create, and passes in the GITHUB_TOKEN.

A simplified ./.github/actions/schedule-merge.js file would look like this (See gr2m/merge-schedule-action/lib/handle_pull_request.js for a complete version).

// make sure to `npm install @octokit/action`
const { Octokit } = require("@octokit/action");

scheduleMerge()

async function scheduleMerge() {
  const octokit = new Octokit();

  // retrieve the full `pull_request` event payload
  const eventPayload = require(process.env.GITHUB_EVENT_PATH);

  // find and parse the date string from the `/schedule ...` command
  const datestring = getScheduleDateString(eventPayload.pull_request.body);

  if (!datestring) {
    console.log(`No /schedule command found`);
    return;
  }

  // Create a check run using the REST API
  // https://developer.github.com/v3/checks/runs/#create-a-check-run
  const { data } = await octokit.request('POST /repos/:owner/:repo/check-runs', {
    owner: eventPayload.repository.owner.login,
    repo: eventPayload.repository.name,
    name: "Merge Schedule",
    head_sha: eventPayload.pull_request.head.sha,
    status: "in_progress",
    output: {
      title: `Scheduled to me merged on ${datestring}`,
      summary: "TO BE DONE: add useful summary"
    }
  });
  console.log(`Check run created: ${data.html_url}`);
}

Now each time you create a pull request or update its description, the action will run and set a pending status if a /schedule ... command is found.

Merge a scheduled pull request

You can create the workflow file for the 2nd step as .github/workflows/merge-scheduled.yml. The cron syntax is rather complicated, but the https://crontab.guru/ website can be a great help.

name: Merge Scheduled Pull Requests
on:
  schedule:
    # https://crontab.guru/every-day-8am
    - cron: 0 8 * * *

jobs:
  merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: "npm ci"
      - run: "node ./.github/actions/merge.js"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

A simplified ./.github/actions/merge.js file would look like this (See gr2m/merge-schedule-action/lib/handle_schedule.js for a complete version).

const { Octokit } = require("@octokit/action");

merge()

async function merge() {
  const octokit = new Octokit();
  const [owner, repo] = process.env.GITHUB_REPOSITORY.split("/");

  const pullRequests = await octokit.paginate(
    "GET /repos/:owner/:repo/pulls",
    {
      owner,
      repo,
      state: "open"
    },
    ({ data }) => {
      return data.filter(hasScheduleCommand).map(pullRequest => {
          return {
            number: pullRequest.number,
            html_url: pullRequest.html_url,
            scheduledDate: getScheduleDateString(pullRequest.body)
          };
        });
    }
  );

  console.log(`${pullRequests.length} scheduled pull requests found`);

  if (pullRequests.length === 0) {
    return;
  }

  const duePullRequests = pullRequests.filter(
    pullRequest => new Date(pullRequest.scheduledDate) < new Date()
  );

  console.log(`${duePullRequests.length} due pull requests found`);

  if (duePullRequests.length === 0) {
    return;
  }

  for await (const pullRequest of duePullRequests) {
    await octokit.pulls.merge({
      owner,
      repo,
      pull_number: pullRequest.number
    });
    console.log(`${pullRequest.html_url} merged`);
  }
}

Combining the workflow files

If you like, you can combine the two workflow files above into one, then run the correct script based on the event. It would look like this

name: Merge Scheduled Pull Requests
on:
  pull_request:
    types:
      - opened
      - edited
  schedule:
    # https://crontab.guru/every-day-8am
    - cron: 0 8 * * *

jobs:
  schedule:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: "npm ci"
      - run: "node ./.github/actions/schedule-merge.js"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  merge:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: "npm ci"
      - run: "node ./.github/actions/merge.js"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Learn more about the GitHub Action workflow syntax on GitHub help.

You can find my merge-schedule action on the GitHub Marketplace: https://github.com/marketplace/actions/merge-schedule

Automate npm releases using semantic-release

Gregor Martynus — Fri, 29 Nov 2019 22:39:45 +0000

In an ideal world, the source code of an npm library is in sync with the versions published to the npm registry.

The problem is that the latest package versions published to npm are lacking behind their code. This results in

Frustrated contributors, whose pull requests got merged and now wait to use the new version that includes their fixes or features
Confused users that run into a bug that is marked as resolved on GitHub
Stressed maintainers that are pressured by comments such as "When will this fix be released?" on closed issues and pull requests.

The solution: automation. Enter semantic-release

In a nutshell, semantic-release relies on commit message conventions to calculate and publish a new version of your package. By default, the 3 conventions are

fix: ... prefix in commit subject: triggers a fix release version, e.g. 1.2.3 → 1.2.4
feat: ... prefix in commit subject: triggers a feature version, e.g. 1.2.3 → 1.3.0
BREAKING CHANGE: in commit body: triggers breaking version release, e.g. 1.2.3 → 2.0.0

That is all you need to learn.

Based on these conventions, new versions are continuously published to npm. Your code on GitHub and published versions on npm will never be out of sync again.

But semantic-release does much more than this:

It creates GitHub releases to mirror the versions published to npm and adds changelogs based on above conventions and adds them to the GitHub releases.
It notifies contributors with comments in pull requests and resolved issues that a new version has been released
It lets you control in a single place who can both merge changes into the master branch and publish new versions to npm.

Setup using GitHub Actions

semantic-release supports a variety of CI providers, git hosts and package registries. For this example, I'll use GitHub Actions to publish to npm.

Install semantic-release

npm install --save-dev semantic-release

If this is an existing project, make sure to create a git tag that matches the last version in the npm registiry, using a v prefix. For example, if the last version published to npm is 2.0.4, create a v2.0.4 tag and push it to your repository.

git tag v2.0.4
git push --tags

No need to create a tag for new packages that have not yet been published.

Next, replace the version in your package.json file with "0.0.0-development". The version will be updated automatically by semantic-release. You no longer need to worry about it.

Next, create an npm token for your account at https://www.npmjs.com/settings/[YOUR USERNAME]/tokens with the read and publish setting. Copy that token and store it in your repository's secrets using the name NPM_TOKEN.

Finally, create a .github/workflows/release.yml file to run semantic-release each time a change is pushed to your repository's master branch.

name: Release
on:
  push:
    branches:
      - master

jobs:
  release:
    name: release
    runs-on: ubuntu-latest
    steps:
      # check out repository code and setup node
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: "12.x"
      # install dependencies and run semantic-release
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

That's it. Next time you merge a pull request with commit messages following the conventions mentioned above, semantic-release will create the npm and GitHub releases as well as comments on the pull request and linked issues.

Closing words

You can see semantic-release in action all over my projects on GitHub. I usually make multiple releases each work day. I don't even think about it any longer. It frees up my time and thoughts to focus on the code instead of the chores around it.

And lastly, a tip: automating releases goes hand-in-hand with automating dependency updates. Services such as Greenkeeper even follow the required commit conventions when they send their pull requests. Merging the PRs is all it takes to release a new version. I highly recommend to use them both!

Automate updates of prettier, standard and other JavaScript linting tools using GitHub Actions

Gregor Martynus — Sat, 23 Nov 2019 00:17:58 +0000

Automating npm dependencies using a service such as Greenkeeper is great! I would not be able maintain as many projects without that kind of automation.

However, linters such as Prettier or Standard are different. Every fix or new feature version introduces new formatting rules and might break your tests. If that happens, you end up waking up to notifications such as this:

In this blog post I will automate the updates of Prettier by creating pull requests which include the updated code. It won't prevent the issues from being created, but once merged the issues will get closed automatically.

Setup

Install prettier in a repository if you haven't yet.

npm install --save-dev prettier

Add two scripts to your package.json file: one to lint, and one to fix linting errors when possible:

{
  ...
  "scripts": {
    ...,
    "lint": "prettier --check '{src,test}/**/*' README.md package.json",
    "lint:fix": "prettier --write '{src,test}/**/*' README.md package.json"
  }
}

Adapt the passed file patterns '{src,test}/**/*' README.md package.json as needed to match your files.

Install the Greenkeeper GitHub App. It's free for Open Source! You will receive an initial pull request that will update all your dependencies to their respective latest versions. Merge that pull request to finish the Greenkeeper setup.
Create the file .github/workflows/update-prettier.yml

name: Update Prettier
on:
  push:
    branches:
      - greenkeeper/prettier-*
jobs:
  update_prettier:
    runs-on: ubuntu-latest
    steps:
      # make your repository's code available to the action
      - uses: actions/checkout@v1
      # setup Node 12. Change the version number to your preference
      - uses: actions/setup-node@v1
        with:
          version: 12
      # Install your package dependencies
      - run: npm ci
      # Fix linting errors with the new prettier version
      - run: npm run lint:fix
      # Create a pull request if there are any changes
      - uses: gr2m/create-or-update-pull-request-action@v1.x
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          title: "Prettier updated"
          body: "An update to prettier required updates to your code."
          branch: ${{ github.ref }}
          commit-message: "style: prettier"

This GitHub Action will run on the push event, but only if the branch starts with greenkeeper/prettier-. These are branches created as part of Greenkeeper's real-time monitoring. They get deleted again if your tests pass, otherwise Greenkeeper creates an issue like the ones shown in the screenshot above.

That's it. Next time a new Prettier version is released, you should see the new "Update Prettier" action doing it's thing:

You will see it in action with the next release of Prettier. I hope that will lower your maintenance overhead a little bit! Happy updating!

DEV Community: Gregor Martynus

How to (not) be a mentor to a marginalized person

The line between mentoring and gaslighting a marginalized person is thin.

Being a mentor is like feeding a hungry person.

My mentee is a target for people who wish me harm.

VS Code ProTip™: paste path of active file into terminal

How I created a public dashboard for the WIP GitHub App using Logflare

Github API Authentication - Username & Password (Basic)

How Basic authentication works for the GitHub API

🎩 @octokit/basic-auth

What are the alternatives to Basic authentication

Credit

GitHub API: How to retrieve the combined pull request status from commit statuses, check runs, and GitHub Action results

Update

Storytime

What is a pull request status?

What is the difference between commit statuses and check runs

How to retrieve the combined status for a pull request

See it in action

Credit

GitHub API Authentication - GitHub Actions

Prerequisites

Passing the GITHUB_TOKEN secret to a JavaScript file

Creating a comment using JavaScript

Secrets and pull requests from forks

GitHub API Authentication - Personal Access Tokens

Using the JavaScript Octokit

Handling errors

Limitations

GitHub API Authentication - Introduction

Example

Schedule GitHub Pull Request merges using Actions

How it works

Set the date for the merge

Merge a scheduled pull request

Combining the workflow files

Automate npm releases using semantic-release

Setup using GitHub Actions

Closing words

Automate updates of prettier, standard and other JavaScript linting tools using GitHub Actions

Setup

🎩 `@octokit/basic-auth`

Passing the `GITHUB_TOKEN` secret to a JavaScript file