Tag: github

Configuration of the HTML5-Boilerplate Git Project and GitHub Repo

Posted on by Rob Larsen

This post outlines the configuration of the HTML5-Boilerplate repo as well as the basic process we use to manage the project. As Github has matured as a platform and HTML5 Boilerplate has matured as a project there are a lot of lessons to be learned from the way we run the show here.

GitHub configuration

This section will go through the way we configure the repo in GitHub. Open source projects get the full power of the platform and as a project we like to experiment with new GitHub features. Our current configuration might help you figure out some things you want to do in your own projects.

General Configuration

This section outlines the basic configuration options we use.

  • We have a stub of a Wiki still, so we have wikis turned on. The most interesting page that remains is a history of the project written several years ago.
  • We use the Issues feature heavily. We don’t yet have Issue Templates set up, but we do have adding them as an issue, so we’ll take advantage of them at some point.
  • Discussions are enabled, but they haven’t been very useful so far.

Pull Requests

The most visible portion of our configuration is the way we handle pull requests. At the most basic level, we require pull requests to add code to the repo and require a review to merge code. In addition we run several code quality checks on every pull request to make sure we’re not introducing anything we don’t want into the codebase.

We take advantage of the “draft” feature for PRs. This way we have visibility throughout the life of the PR.

Let’s take a look at how we configure our main branch.

main

main is the default branch and is our only protected branch. We use feature branches to add features and/or fix issues in the codebase. Other project configurations might require a long-running, similarly protected, development branch but for us the single protected main branch is enough for our purposes.

Our branch protection rules are as follows:

  • We require a pull request (PR) with one approving reviewer to merge code
  • In addition to the PR and approving reviewer, we require three status checks to pass before code can be merged
    • Build with Node 16
    • Build with Node 14
  • We allow force pushes for project admins. While force pushes can create some head scratching moments for people who have cloned the repo and update before and after the force push, the ability to clean up the HEAD of a public branch like this in an emergency is useful.

GitHub Actions and Other Checks That Run on main

  • We run a simple build status check. This is the most basic test you can run and is absolutely vital. If you can’t build your project you’re in trouble. Currently we’re testing against Node 14 and 16.
  • We take advantage of our access to CodeQL analysis Free for research and open source don’t you know 🙂 We don’t have a ton of surface area to cover, but it’s nice to have this powerful code scanning tool available to us.
  • We run a dependency review scan to see if any newly added dependencies add known security flaws. This is important for even us, but for a project that uses a larger number of third party dependencies, this sort of check is vital.
  • We push any changes to main to our HTML5-Boilerplate Template Repo

Since we’ve talked about some of our Actions, let’s look at the full configuration of our .github folder.

.github Folder

  • workflows
    • build-dist.yaml is currently broken. We can’t push to main without a code review, so this task is blocked. What I would like, (are you there, GitHub, it’s me, Rob) is to allow Actions to bypass branch protection rules. I think we’ll have to basically write a mini-bot that opens a PR whenever there are changes to main and then pushes to the same branch until the PR is closed. In some ways that will be better as it will be less noisy in terms of bot pushes to main.
    • codeql-analysis.yml controls our CodeQL action. We use the defaults. If you’re building something with more JAvaScript footprint, you can tweak the settings for this job.
    • dependency-review.yml does what it says on the tin- it tests newly introduced dependencies for vulnerabilities.
    • publish.yaml is the action that publishes all the various versions of the project. When we create a new tag and push it to GitHub, this script publishes our npm package and creates a GitHub release and attaches a zip file of our dist folder.
    • push-to-template.yaml pushes the HEAD of main to our template repo
    • spellcheck.yml automatically checks markdown files for typos with cSpell.
    • test.yaml runs our test suite.
  • CODE_OF_CONDUCT.md is our Code of Conduct, based on Contributor Covenant.
  • CONTRIBUTING.md contains our contribution guidelines.
  • ISSUE_TEMPLATE.md is our new issue boilerplate.
  • PULL_REQUEST_TEMPLATE.md is our new PR boilerplate.
  • SUPPORT.md points people to different (non-HTML5-Boilerplate) support resources
  • dependabot.ymlis our Dependabot configuration. We do npm, monthly on two separate package.json files, one in src and one in project root.

That covers most of the interesting GitHub features and functionality that we use. We’re going to continue to keep this document up to date as we change things or new GitHub features.

How Did I Miss This?

Posted on by Rob Larsen

Apparently, if you make a repo with a name that matches your username, you can add the contents of the associated Readme.md to your public GitHub profile.

Basically, if you create this: roblarsen/roblarsen the contents of https://github.com/roblarsen/roblarsen/blob/main/README.md will be displayed at the top of https://github.com/roblarsen

That’s pretty cool!

New HTML5 Boilerplate Template Repository

Posted on by Rob Larsen

Hey! It’s been a while. Sorry! I’m going to have a lot more content to share over the next few months, so get used to me writing again.

Anyway, we’re in the middle of creating HTML5 Boilerplate 9.0. As part of that release we have created a Github template repository.

As GitHub wrote when they unveiled the feature

Sharing boilerplate code across codebases is a constant pattern in software development. Bootstrapping a new project with our favorite tools and directory structures helps programmers go from idea to “Hello world!” more efficiently and with less manual configuration.

Today, we’re excited to introduce repository templates to make boilerplate code management and distribution a first-class citizen on GitHub. To get started, all you need to do is mark a repository as a template, and you’ll immediately be able to use it to generate new repositories with all of the template repository’s files and folders.

With all the mentions of “boilerplate” it’s like template repos were made for HTML5 Boilerplate. Nice.

Using them is pretty simple.

First, navigate to h5bp/html5-boilerplate-template. Once there, click on the “Use this template”

Next, you add the name you would like to use:

And that’s it. You’ve got a fresh repo with all the files from HTML5 Boilerplate ready to go.

That’s just a taste of the changes on offer. I’ll have more news as we get closer to the final release. I would love to have this release out before 2021 is over. We’ll see!

Using Github Actions to Publish the HTML5 Boilerplate npm Package

Posted on by Rob Larsen

We just released HTML5 Boilerplate 7.3.0. As part of that release we integrated Github Actions in order to publish our npm package when we cut a Github release. Doing so was pretty easy. This is how I ended up doing it.

To start, I enabled Github Actions for the repo. To do so check “Enable local and third party Actions for this repository” on the “settings/actions” tab of the repository.

Next, I created a workflows directory inside our .github folder and added a new file called npmpublish.yml

Here’s what that file looks like. It’s based on one of the default Actions that Github provides, conveniently.


name: publish npm

on:
  release:
    types: [published]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: npm ci
      - run: npm run build

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org/
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

Let’s go through what it does. The first line gives the action its name. 


name: publish npm

This is the name that will show up in the Actions tab within Github.

The next section indicates that this action should run on a release event, specifically when a release is published. Github releases are basically enhanced git tags and we use them to neatly package up our dist folder for easy consumption as a zip folder. The type property actually accepts a list, but since we’re publishing to npm, we only want to do this when the code is actually released. 


on:
  release:
    types: [published]

The next section contains the jobs that we will run, build and publish.

First up is build. I just used the default runs-on option- ubuntu-latest, since I’m not doing anything particularly fancy. This just means my work will run on a machine running Ubuntu.

Following that are some default Actions:

  • actions/checkout@v1, which checks out your repository, so that your workflow can access the contents of your repository.
  • actions/setup-node@v1, which installs a specific version of node for your project to use. In our case we’re using node version 12.

Finally, with the environment set up, we run two commands. npm ci, which is a continuous integration version of the more familiar npm install command. npm ci uses package-lock.json and some other optimizations to build out node_modules dependencies more quickly than npm install. Then we run npm run build which is our standard build command. That is an alias for gulp build and it generates the contents our our dist folder. 


 build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: npm ci
      - run: npm run build

At this point we’re ready to publish to npm. That happens in our next job, npm-publish. Here we have a new wrinkle, the needs property. This just means that it requires the previous build job to be there before it can run. After that, the setup is similar. It runs on ubuntu-latest, it checks out the code and sets up our node environment. The one change in the environment set-up is that it sets the registry-url to https://registry.npmjs.org/. This is the default, but your organization might have a different private registry. You would set that here.

Finally, we run npm publish which does the actual job of publishing the project out to npm. This is just the standard npm command. This command uses the environment variable NODE_AUTH_TOKEN for authentication. The following section shows how to set up authentication for npm. 


 publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org/
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

To set up a token to use for authentication with npm, first go to npmjs.com/ and open up the tokens page.

Click on the “create new token” button.

Select “read and publish.”

Copy the newly created token.

Head over to Github. Click on “settings” and then “secrets.” Add a new secret. Call it npm_token and then paste in the npm token.

And that’s that. Authentication for npm is set up.

This is just a basic example of what you can do with Github Actions, but was super convenient for me, so I thought it was worth sharing.