overbit/github-workflows

reusable shared CI scripts

Github Workflows

Reusable workflows and actions

Opinionated publish process for npm

github is the source of truth for code AND releases. Get the version/tag/release right on github, then publish to npm based on that.

1. work on a feature branch, commiting with conventional-commits
2. merge to main
3. A push to main produces (if your commits have fix: or feat:) a bumped package.json and a tagged github release via githubRelease
4. A release cause npmPublish to run.

Just need to publish to npm? You could use any public action to do step 4. Use this repo's npmPublish if you need either

1. codesigning for Salesforce CLIs
2. integration with CTC or if you own other repos that need those features and just want consistency.

githubRelease

creates a github release based on conventional commit prefixes. Using commits like fix: etc (patch version) and feat: wow (minor version). A commit whose body (not the title) contains BREAKING CHANGES: will cause the action to update the packageVersion to the next major version, produce a changelog, tag and release.

name: version, tag and github release

on:
  push:
    branches: [main]

jobs:
  release:
    uses: salesforcecli/github-workflows/.github/workflows/githubRelease.yml@main
    secrets: inherit

npmPublish

This will verify that the version has not already been published. There are additional params for signing your plugin and integrating with Change Traffic Control (release moratoriums) that you probably only care about if your work for Salesforce.

example usage

on:
  release:
    # the result of the githubRelease workflow
    types: [published]

jobs:
  my-publish:
    uses: salesforcecli/github-workflows/.github/workflows/npmPublish.yml
    with:
      tag: latest
      githubTag: ${{ github.event.release.tag_name }}
    secrets: inherit

Prereleases

main will release to latest. Other branches can create github prereleases and publish to other npm dist tags

1. Configure the branch rules for wherever you want to release from
2. Set your branch's package.json version like 4.4.4-beta.0
3. Modify your release and publish workflows like the following

name: version, tag and github release

on:
  push:
    branches:
      - main
      # point at specific branches, or a naming convention via wildcard
      - prerelease/*
    tags-ignore:
      - "*"

jobs:
  release:
    # this job will throw if prerelease is true but it doesn't have a prerelease-looking package.json version
    uses: salesforcecli/github-workflows/.github/workflows/githubRelease.yml@main
    secrets: inherit
    with:
      prerelease: ${{ github.ref_name != 'main' }}

name: publish

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      tag:
        description: tag that needs to publish
        type: string
        required: true

jobs:
  # parses the package.json version and detects prerelease tag (ex: beta from 4.4.4-beta.0)
  getDistTag:
    outputs:
      tag: ${{ steps.distTag.outputs.tag }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          ref: ${{ github.event.release.tag_name || inputs.tag  }}
      - uses: salesforcecli/github-workflows/.github/actions/getPreReleaseTag@main
        id: distTag

  npm:
    uses: salesforcecli/github-workflows/.github/workflows/npmPublish.yml@main
    needs: [getDistTag]
    with:
      tag: ${{ needs.getDistTag.outputs.tag || 'latest' }}
      githubTag: ${{ github.event.release.tag_name || inputs.tag }}
    secrets: inherit

Publishing from multiple long-lived branches

In this example main publishes to npm on a 1.x.x version and uses latest. some-other-branch publishes version 2.x.x and uses the v2 dist tag

name: version, tag and github release

on:
  push:
    # add the other branch so that it causes github releases just like main does
    branches: [main, some-other-branch]

jobs:
  release:
    uses: salesforcecli/github-workflows/.github/workflows/githubRelease.yml@main
    secrets: inherit

on:
  release:
    # the result of the githubRelease workflow
    types: [published]

jobs:
  my-publish:
    uses: salesforcecli/github-workflows/.github/workflows/npmPublish.yml
    with:
      # ternary-ish https://github.com/actions/runner/issues/409#issuecomment-752775072
      # if the version is 2.x we release it on the `v2` dist tag
      tag: ${{ startsWith( github.event.release.tag_name || inputs.tag, '1.') && 'latest' || 'v2'}}
      githubTag: ${{ github.event.release.tag_name }}
    secrets: inherit

Opinionated Testing Process

Write unit tests to tests units of code (a function/method).

Write not-unit-tests to tests larger parts of code (a command) against real environments/APIs.

Run the UT first (faster, less expensive for infrastructure/limits).

name: tests
on:
  push:
    branches-ignore: [main]
  workflow_dispatch:

jobs:
  unit-tests:
    uses: salesforcecli/github-workflows/.github/workflows/unitTest.yml@main
  nuts:
    needs: unit-tests
    uses: salesforcecli/github-workflows/.github/workflows/nut.yml@main
    secrets: inherit
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
      fail-fast: false
    with:
      os: ${{ matrix.os }}

Other Tooling

nut conditional on commit message

# conditional nuts based on commit message includes a certain string
sandbox-nuts:
  needs: [nuts, unit-tests]
  if: contains(github.event.push.head_commit.message,'[sb-nuts]')
  uses: salesforcecli/github-workflows/.github/workflows/nut.yml@main
  secrets: inherit
  with:
    command: test:nuts:sandbox
    os: ubuntu-latest

externalNut

Scenario

1. you have NUTs on a plugin that uses a library
2. you want to check changes to the library against those NUTs

see https://github.com/forcedotcom/source-deploy-retrieve/blob/> e09d635a7b852196701e71a4b2fba401277da313/.github/workflows/test.yml#L25 for an example

automerge

This example calls the automerge job. It'll merge PRs from dependabot that are

1. up to date with main
2. mergeable (per github)
3. all checks have completed and none failed (skipped may not have run)

name: automerge
on:
  workflow_dispatch:
  schedule:
    - cron: "56 2,5,8,11 * * *"

jobs:
  automerge:
    uses: salesforcecli/github-workflows/.github/workflows/automerge.yml@main
    # secrets are needed
    secrets: inherit

need squash?

automerge:
  with:
    mergeMethod: squash

versionInfo

requires npm to exist. Use in a workflow that has already done that

given an npmTag (ex: 7.100.0 or latest) returns the numeric version (foo => 7.100.0) plus > the xz linux tarball url and the short (7 char) sha.

Intended for releasing CLIs, not for general use on npm packages.

# inside steps
- uses: salesforcecli/github-workflows/.github/actions/versionInfo@main
  id: version-info
  with:
    version: ${{ inputs.version }}
    npmPackage: sfdx-cli
- run: echo "version is ${{ steps.version-info.outputs.version }}
- run: echo "sha is ${{ steps.version-info.outputs.sha }}
- run: echo "url is ${{ steps.version-info.outputs.url }}

validatePR

Checks that PRs have a link to a github issue OR a GUS WI in the form of @W-12456789@ (the @ are to be compatible with git2gus)

name: pr-validation

on:
  pull_request:
    types: [opened, reopened, edited]
    # only applies to PRs that want to merge to main
    branches: [main]

jobs:
  pr-validation:
    uses: salesforcecli/github-workflows/.github/workflows/validatePR.yml@main

prNotification

Mainly used to notify Slack when Pull Requests are opened.

For more info see .github/actions/prNotification/README.md

name: Slack Pull Request Notification

on:
  pull_request:
    types: [opened, reopened]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Notify Slack on PR open
        env:
          WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
          PULL_REQUEST_AUTHOR_ICON_URL: ${{ github.event.pull_request.user.avatar_url }}
          PULL_REQUEST_AUTHOR_NAME: ${{ github.event.pull_request.user.login }}
          PULL_REQUEST_AUTHOR_PROFILE_URL: ${{ github.event.pull_request.user.html_url }}
          PULL_REQUEST_BASE_BRANCH_NAME: ${{ github.event.pull_request.base.ref }}
          PULL_REQUEST_COMPARE_BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
          PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
          PULL_REQUEST_REPO: ${{ github.event.pull_request.head.repo.name }}
          PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}
          PULL_REQUEST_URL: ${{ github.event.pull_request.html_url }}
        uses: salesforcecli/github-workflows/.github/actions/prNotification@main