branch-deploy/README.md

Branch Deploy Action 🚀

A GitHub Action to enable branch deployments using IssueOps!

About 💡

Before we get into details, let's first define a few key terms below:

• IssueOps - Its like ChatOps but instead of using a chat bot, commands are invoked by commenting on a pull request (PRs are issues under the hood) - Example: commenting .deploy on a pull request
• Branch Deployment - A branch deploy is a deployment methodology that enables you to deploy a branch (or pull request) to a desired environment before merging to main or master - More on this below
• PR - Short for pull request

IssueOps 🗨️

The best way to define IssueOps is to compare it to something similar, ChatOps. You may be familiar with the concept ChatOps already but in case you aren't here is a quick definition below:

ChatOps is the process of interacting with a chat bot to execute commands directly in a chat platform. For example, with ChatOps you might do something like .ping example.org to check the status of a website

IssueOps adopts the same mindset but through a different medium. Rather than using a chat service to invoke the commands we use comments on a GitHub Issue or Pull Request. GitHub Actions is the runtime which executes our desired logic

Branch Deployments 🌲

Branch deployments are a battle tested way of deploying your changes to a given environment for a variety of reasons. Branch deployments allow you to do the following:

• Deploy your changes to production before merging
• Deploy changes to a staging, QA, or non-production environment

Branch Deployment Core Concepts ⭐

Note: The main branch is considered the base repository branch for all examples below

• The main branch is always considered to be a stable and deployable branch
• All changes are deployed to production before they are merged to the main branch
• To roll back a branch deployment, you deploy the main branch
• noop deployments should not make changes but rather report what they "would" have done

Why use branch deployments?

To put the merge -> deploy model in the past!

What if your changes are bad and you broke production with the merge -> deploy model? Well now you have to revert your PR, get passing CI/builds, and then re-merge your changes to get back to a stable environment. With the branch deploy model, this is almost never the case. The main branch is considered to be always safe and stable

Testing Locally 🔨

Test with act locally to simulate a GitHub Actions event

act issue_comment -e events/issue_comment_deploy.json -s GITHUB_TOKEN=faketoken -j test

Create an action from this template

Click the Use this Template and provide the new repo details for your action

Code in Main

First, you'll need to have a reasonably modern version of node handy. This won't work with versions older than 9, for instance.

Install the dependencies

$ npm install

Build the typescript and package it for distribution

$ npm run build && npm run package

Run the tests ✔️

$ npm test

 PASS  ./index.test.js
  ✓ throws invalid number (3ms)
  ✓ wait 500 ms (504ms)
  ✓ test runs (95ms)

...

Change action.yml

The action.yml defines the inputs and output for your action.

Update the action.yml with your name, description, inputs and outputs for your action.

See the documentation

Change the Code

Most toolkit and CI/CD operations involve async operations so the action is run in an async function.

import * as core from '@actions/core';
...

async function run() {
  try { 
      ...
  } 
  catch (error) {
    core.setFailed(error.message);
  }
}

run()

See the toolkit documentation for the various packages.

Publish to a distribution branch

Actions are run from GitHub repos so we will checkin the packed dist folder.

Then run ncc and push the results:

$ npm run package
$ git add dist
$ git commit -a -m "prod dependencies"
$ git push origin releases/v1

Note: We recommend using the --license option for ncc, which will create a license file for all of the production node modules used in your project.

Your action is now published! 🚀

See the versioning documentation

Validate

You can now validate the action by referencing ./ in a workflow in your repo (see test.yml)

uses: ./
with:
  milliseconds: 1000

See the actions tab for runs of this action! 🚀

Usage:

After testing you can create a v1 tag to reference the stable and latest V1 action