Note: The following section requires you to create a repository on your own account. You will need to ensure you have access to the Actions and Package Registry beta by navigating to the features page.
Next let’s start a new project in your personal repos (not the github-craftwork org) using the github-craftwork/ci-template. The contents of the project include JavaScript that finds out what the current week number it is today.
Create a CI pull requests
To develop a GitHub Workflow process that employs Actions to automate the Continuous
Integration process, you can begin by adding starter workflow file to the .github directory. On the initial view of your repository, find and navigate to the Actions tab.
On the Actions page you should see 2 JavaScript workflow options. Find the Node.js (the one that is not a Package) option and click the Set up this workflow button.
Note: The actions/starter-workflows repository contains many sample workflow files.
The Actions Workflow wizard will install the sample workflow selected in your repo within the .github folder. You may edit the name of the file and its contents on the screen provided.
Commit the nodejs.yml file to the main branch to complete this process of creating our first CI workflow.
The .github/workflows/ folder will include the contents from below:
name: Node CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [10.x, 12.x, 14.x]
steps:
- uses: actions/checkout@v2
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node-version }}
- run: npm ci
- run: npm run build --if-present
- run: npm test
Take note that our workflow is running a strategy with 3 versions of node, [10, 12 and 14]. This will be important to know later.
Because your new Actions CI is running on everything push, you should already have a workflow running.
Note that we will need to run a test to run as part of our CI, Find the index.test.js file with the contents from below:
// index.test.js
const weekNum = require('./index.js');
test('that weekNum returns a value', () => {
expect(weekNum).not.toBeNull();
});The result of that last push to main should look like this image:
Add another test Let’s add another test to ensure we have 200% test coverage.
const weekNum = require('./index.js');
test('that weekNum returns a value', () => {
expect(weekNum).not.toBeNull();
});
// new test added
test('that weekNum returns a number', () => {
expect(weekNum).toBeDefined();
});Add the above test using the UI, but instead of committing directly to the main branch, open a pull request to trigger you CI workflow again..
We have not created a pull request until now, so please take note that you can see all the workflows triggering through a GitHub Check Suite. All Action Workflows are being powered by this API feature. And since we are on the subject the GitHub Actions bot is built on the GitHub App framework that has already popularized by a number of our Marketplace and Ecosystem partners.
Once all test have passed, merge the pull request and let us move on to complete the next step.
The GitHub Actions workflow allows users to take advantage of a vast selection of open source tooling and solutions. Since the Actions workflow 'runners' are in themselves Virtual Machines (VMs) running on cloud servers. This is different from the GitHub App workflow, which requires you to host it on your own server.
Learn more on the strengths of GitHub Actions and GitHub Apps in the developer guides.
Our package.json has no build step, and our nodejs.yml is specifically looking for one, so let’s add that.
Add build script
In the package.json add a new line to the script that runs npx and parcel in the VM. npx parcel build index.js is a script that will install parcel on the VM and bundle the index.js in one step.
// package.json
"scripts": {
"test": "jest", // add the comma
"build":"npx parcel build index.js" // add this line
},Note: The scripts is a comma separated list, be sure add the comma to the previous script test script when adding the build script.
You will now see that the build step completes and provides a bundle version of our Javascript.
In situations where you would like a smaller file size package distribution this is important to do, but build is one thing — what else can we do? Move on to the next to step to learn what else you can at build time.
Our project is missing something else, a linter. We can add this the same way we added the build script. In the package.json, add the lint key with the value as npx standard.
// package.json
"scripts": {
"test": "jest",
"build":"npx parcel build index.js", // add the comma
"lint": "npx standard --fix" // add this line
},We will also need to add a step to our linter as a separate job in our nodejs.yml.
To do this we will use the Node Code Formatter Action.
Add formatter workflow
Add the following code to your existing nodejs.yml and open a pull request with this change.
jobs:
lint:
name: Node Code Formatter
runs-on: ubuntu-latest
steps:
- name: Node Code Formatter
uses: MarvinJWendt/[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
This update will check your code for lint issues and fix them for you. When the Action completes you will see a commit appear that looks similar to this:
That completes this section, move on to the next section to learn how to automate your release workflow.
CI is often coupled with the idea of Continuous Delivery (CD). The next two sections will cover automating your projects release management.
Add release workflow
You can use the Release Drafter GitHub Action in a GitHub Actions Workflow by configuring a YAML-based workflow file, e.g. .github/workflows/release-management.yml, with the following:
name: Release Management
on:
push:
# branches to consider in the event; optional, defaults to all
branches:
- main
jobs:
update_draft_release:
runs-on: ubuntu-latest
steps:
# Drafts your next Release notes as Pull Requests are merged into "main"
- uses: toolmantim/[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Once you’ve added Release Drafter to your repository, it must be enabled by adding a .github/release-drafter.yml configuration file to each repository.
Add release template
Create the following .github/release-drafter.yml file in a repository and commit to your main branch:
template: |
## What’s Changed
$CHANGES
Make a change Navigate to your package.json file in the repo and replace the contents with your details. Be sure to create merge a PR for this change instead of write to main.
Change: Swap out my name with your handle and commit that to main.
As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready:
To test this workflow, edit your draft using the existing tag created for it. Once completed, move on to the next step in the project to complete this step.
We have been using npm for some basic script commands thus far, npm, short for Node Package Manager, is two things: first and foremost, it is an online repository for the publishing of open-source Node.js projects; second, it is a command-line utility for interacting with said repository that aids in package installation, version management, and dependency management. A plethora of node.js libraries and applications are published on npm, and many more are added every day. These applications can be searched for on search.npmjs.org/..
Now let’s put our work on npm to share.
Return to the Actions tab and select the “New workflow” button.
Add package workflow First create an npm account if you do not.
Navigate back to the Actions tab and find the “New Workflow” button to expose the wizard. Select the Node.js Package and set up that workflow.
The file will require a changes. We only want to publish packages after they have been merged to main.
The default setup runs this workflow on all open pull requests. This is not needed and will need to be removed. This workflow should only run on pushes to main.
name: Node.js Package
on:
push:
branches:
- main
Scrolling through the npmpublish.yml you will see 3 jobs:
- build - running tests
- publish-npm
- publish-gpr
Publish to npm
The first two you are familiar based on the content we went through so far. The publish-npm requires a secrets.npm_token which I which you will need to share generate on npm.com.
Add npm_token secrets You can provide you secret by navigating to your repository’s settings. There you will see a Secrets menu item.
Add your npm token
Publish to public npm requires a payment on file to publish private packages. You will need to add add a public flag to the publish script.
publish-npm:
...
- run: npm publish --access public // add this public access flag
Publish to GitHub Package Registry Note: [The Package Registry feature is in public beta.
The next job is publish-gpr.
You will need to replace the “@your-github-username” with your username.
GitHub Package Registry is a software package hosting service, similar to npmjs.org, rubygems.org, or hub.docker.com, that allows you to host your packages and code in one place. You can host software packages privately or publicly and use them as dependencies in your projects.
Create a PR for this workflow Commit this workflow to a new branch and open the pull request.
Before you merge these changes to main, head over to the package.json and replace the git URL to match the repo you are working out of and replace the GitHub handles to yours.
To start the npmpublish workflow, merge the PR.
