Clean Releases and Changelogs with Github Actions

Libraries Used in Custom Action

• standard version
• commit lint
• husky

What are GitHub Actions ?

Types of GitHub Actions

• Composite Actions
• Reusable Workflow Actions

Differences between Composite & Reusable Workflow Actions

Composite Actions

Reusable Workflows

Benefits of working with Composite Actions

Exploring Event Options for a Composite Action

Unleashing Manual Control : workflow_dispatch

“Unlike events triggered automatically by system events, workflow_dispatch allows you to start a workflow manually.”

Bringing inputs into the Equation

Combining workflow_dispatch and inputs

How to Automate Releases with GitHub Actions

First step to a GitHub CI Workflow : Implement your Service Repository

• In your GitHub repository, navigate to the Actions tab.

• Click on the Set up a workflow yourself button to create a new workflow file.

• Create a folder at the root of your repo and name it workflow. From there, add a file inside thsi folder and name it - workflow/ci-release.yml. This is where you'll define your workflow for automating releases and changelogs. You can now add the following code in this file :

name: ci-release
description: ci release in service

permissions:
  actions: write
  checks: write
  contents: write
  deployments: write
  id-token: write
  issues: write
  discussions: write
  packages: write
  pages: write
  pull-requests: write
  repository-projects: write
  security-events: write
  statuses: write

on: 
  workflow_dispatch:
    inputs:
      release_type:
        description: 'bump version kind'
        required: true
        default: 'patch'
        type: choice
        options:
          - patch
          - minor  
          - major
          
jobs:
  create-staging:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: create staging branch 
      if: !exists('staging')
      run: |
        git checkout -b staging
        git push --set-upstream origin staging

  release:
    needs: create-staging 
    runs-on: ubuntu-22.04

    steps:
    - uses: actions/checkout@v2
    - name: release
      uses: organization-name/action-release@v0.0.1
      with:
        release_type: ${{ inputs.release_type }}
        push_to: staging 
        publish_type: 'service'
        secret_input: ${{ secrets.GITHUB_TOKEN }}

Service Yml Codes Breakdown

• create-staging : creates a staging branch if it doesnt exist and pushes changes there
• release : a custom job to create a release. This job uses an external action located in the organization-name/action-release@v0.0.1 repository that well create next.

• name : this specifies the name of the workflow. Here it is ci-release which describes that this is a CI (continuous integration) workflow for releasing code.
• description : as you noted, this provides a human-readable description of what the workflow does.
• uses : the uses keyword indicates that this step will run an action - a reusable component encapsulating code. Here it is using a custom action defined in the organization.
• permissions : this specifies the GitHub permissions required for the workflow to access different resources like code, issues, etc.
• on : triggers the workflow on push events to main branch, as you noted.
• jobs : jobs define the actual work to be executed. Here there is a single job called release.
• runs-on : specifies the type of virtual environment the job will run on. Here it is an Ubuntu runner.
• steps : defines the sequence of tasks to execute in the job. Each is a separate step.
• uses & with : in each step, uses indicates the action to run, and with passes inputs to that action.

Configuration Files

• package.json file to host the libraries we mentioned

{
	"name": "@organization-name/service-name",
	"version": "0.0.1",
	"repository": "git@github.com:organization-name/service-name.git",
	"author": "organization-name",
	"scripts": {
		"prepare": "husky install"
	},
	"dependencies": {
		"husky": ">=8.0.3"
	},
	"devDependencies": {
		"@commitlint/cli": "^17.6.6",
		"standard-version": "^9.5.0",
		"@commitlint/config-conventional": "^17.6.6"
	}
}

• .versionrc.js file to configure standard-version

const versionConfig = {
  bumpFiles: [{ filename: "package.json", type: "json" }],
  commitAll: true,
  commitMessageFormat: "chore(release): {{currentTag}}",
  issuePrefixes: "organization_name-",
  commitPaths: ["package.json", "package-lock.json"],
  types: [
    { type: "feature", section: "✨ feature" },
    { type: "design", section: "⚜️ design" },
    { type: "build", section: "👷 build" },
    { type: "bug", section: "🐛 bug fixes" },
    { type: "chore", hidden: false, section: "🚚 chore" },
    { type: "devop", hidden: false, section: "🆙 devop" },
    { type: "documentation", hidden: false, section: "📝 documentation" },
    { type: "style", hidden: false, section: "💄 styling" },
    { type: "refactor", hidden: false, section: "♻️ code refactoring" },
    { type: "performance", hidden: false, section: "⚡️ performance improvement" },
    { type: "ux", hidden: false, section: "🔥 ux change" },
    { type: "test", hidden: false, section: "✅ testing" },
  ],
};

module.exports = versionConfig;

• commitlint.config.js to configure your commit validations

const commitlintConfig = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "subject-empty": [1, "never"],
    "references-empty": [1, "never"],
    "scope-empty": [1, "never"],
    "type-enum": [
      2,
      "always",
      [
        "design",
        "build",
        "chore",
        "devops",
        "documentation",
        "feature",
        "bug",
        "performance",
        "refactor",
        "style",
        "design",
        "ux",
        "test",
      ],
    ],
  },
  parserPreset: {
    parserOpts: {
      issuePrefixes: ["organization_name-"],
    },
  },
};

module.exports = commitlintConfig;

• husky.config.js file to provide what hooks need to run prior to your commits and run linting

module.exports = {
	hooks: {
		"pre-commit": "lint-staged",
	},
};

Create a Changelog Document

# command to create a changelog
touch CHANGELOG.md

Second step to a GitHub CI Workflow : Implementation of a Composite Action in a ci repository

• Create a new repository for the composite action : in this new repository, you'll implement the Composite Action that will be used in your service to automate releases.
  • You can name it : action-release to stick to the example above.

• Create the action file action.yml : in the root of your new repository, create a file named action.yml with the following content :

name: ci-release
description: ci release in ci repo

inputs:
  secret_input:
    description: 'github secret from service repo'
    required: true
    default: ''
  release_type:
    description: 'bump version type'
    required: true
    default: 'patch'
  publish_type:
    description: 'publish type'
    required: false
    default: 'service'
  push_to:
    description: 'push to new branch after releasing'
    default: 'none'
  pre_action:
    description: 'allowed values : checkout, none'
    default: 'checkout'

runs:
  using: "composite"
  steps:
    - name: checkout repo
      if: ${{ inputs.pre_action == 'checkout' }}
      uses: actions/checkout@v3
      with:
        fetch-depth: 0
    - name: setup node
      uses: actions/setup-node@v3
      with:
        registry-url: 'https://npm.pkg.github.com'
        node-version: '16'
    - name: git authentication
      shell: bash
      run: |
          git config --global user.email "release_username@provider.com"
          git config --global user.name "release username"
    - name: bump version, tag and create changelog
      shell: bash
      run: npx standard-version --release-as ${{ inputs.release_type }}
    - name: push changes
      shell: bash
      run: git push --follow-tags
    - name: publish version
      if: ${{ inputs.publish_type == 'service' }}
      shell: bash
      run: yarn install --frozen-lockfile && yarn publish --non-interactive
      env:
        NODE_AUTH_TOKEN: ${{ inputs.secret_input }}
    - if: ${{ inputs.push_to == 'staging' }}
      uses: ad-m/github-push-action@master
      with:
        branch: staging

CI Repo Yml Codes Breakdown

• secret_input : a GitHub secret input that can be used to provide a Github token or any other sensitive information required by the workflow. It is marked as required and has a default value of an empty string ('') but the secret is called from the service repo.
• release_type : this input is used to specify the type of version bump (major, minor, or patch). It is marked as required and has a default value of 'patch'.
• publish_type : an input to specify the type of publish action (library or service). It is marked as optional and has a default value of 'service'. Due to the publish type, we can have different operations in our CI based on if the targeted repo is a library or a service
• push_to : input to specify whether to push changes to a new branch (staging or none). It is marked as optional and has a default value of 'none'.
• pre_action : an input to specify a pre-action (checkout or none). It is marked as optional and has a default value of 'checkout'.

• run :
  • the run keyword is used to execute shell commands or scripts as part of a step.
  • anything specified under run will be executed by the runner during that step.
  • it is typically used to run shell scripts, build tools, test commands, etc.

• permissions with using: composite :
  • when using a composite action, permissions need to be explicitly defined vs inherited from the base action.
  • this gives more control over what the composite action can access.
  • for example : a composite may need read/write permissions to repository content.

• steps :
  • steps define the series of tasks that make up the action.
  • each step can run commands/scripts inline using run, or reference reusable actions.
  • steps are executed sequentially by the runner.

The Jobs Steps

• checkout repo : checks out code if pre_action is 'checkout'
• setup node : sets up Node.js environment
• git authentication : configures Git user details
• bump version, tag and create changelog : bumps version and generates changelog
• push changes : pushes changes and tags
• publish version : conditionally publishes package if publish_type is 'service'
• push to staging branch : conditionally pushes to staging branch if push_to is 'staging'

Running the Workflow 🏃🏽‍♂️

In Conclusion 🔥