gh-actions-example

This repository serves as an example on:

• How to configure a workflow which notifies Slack, builds and publishes a Docker image, and automatically versions the repo
• How to configure semantic versioning using semantic-release, commitlint, and husky

How to Use This Repository

This repository can be used to experiment with the automated semantic versioning and get familiar with it. The repository MUST be returned back to a working state once done testing.

1. Install dependencies

   # If you use yarn
   yarn
   
   # If you use npm
   npm i

2. Make a minor change and commit it to this repo with a message which follows Conventional Commits. The commit message and TYPE can be whatever you'd like. Push to master when done.

3. View the running action here.

4. Generated release notes can be found here and here.

Configure a Repo with Automatic Semantic Versioning

In order to configure a Git repo with automatic semantic versioning, follow the steps below:

1. Clone the project

2. Create a package.json file

   • Even if your project isn't a Node project, the package.json file serves as a config file for the semantic-release, commitlint, and husky Node modules.

3. Copy the commitlint, husky, and release configuration blocks found in the example package.json to the package.json in your project.

   • You can customize these configurations further using the Node modules' documentation
     • semantic-release docs
     • commitlint docs
     • husky docs

4. Run the following to install the commitlint and husky packages locally and save them as development dependencies to the package.json

   • Only commitlint and husky need to be installed locally, semantic-release does not since it'll only be used by Github Actions.
   • Upon installation of husky, it will attempt to create a pre-commit hook in your git repo
   • If you see errors, resolve them then try re-installing.

   # If you use yarn
   yarn add --dev husky @commitlint/{config-conventional,cli} --force
   
   # If you use npm
   npm i --save-dev husky @commitlint/{config-conventional,cli}

5. Activate hooks

   # If you use yarn
   yarn husky install
   
   # If you use npm
   npx husky install

6. Add hook

   npx husky add .husky/commit-msg 'npx --no-install commitlint --edit'

7. Optional: Add the following files/dirs to the .gitignore file:

   echo -e "**/node_modules" >> .gitignore

8. Add a Github Actions workflow to .github/workflows/

   • Example workflow using semantic-release
   • See the Github Actions documentation for more info

9. Commit all new files/modifications (except for anything being ignored)

   • Upon commit, you should see a pre-commit hook fire which runs commitlint and checks your commit message. Your message must conform to Conventional Commits, otherwise it will be denied by commitlint. If this does not happen or an error occurs, resolve the error then try again.

Going forward, anyone who wishes to commit to your repository will need to run the following command beforehand to install local dev dependencies. It should be quick and only take a few seconds:

    # If you use yarn
    yarn

    # If you use npm
    npm i