Standards and workflows for release engineering repositories
- Release Engineering Repo Standards
The sections below list workflows controlled from this repository.
The Release workflow creates and updates tags and for the reusable workflows themselves, because caller repositories should be referencing these actions via a major version tag according to GitHub Actions best practices.
If there are backwards incompatible changes to any workflow, then it's important to perform a major version bump, so that any caller workflows can be dealt with appropriately.
The workflow will publish a new release tagging the latest commit, and move the major version tag (For example v1
), to the latest commit as well.
To perform a manual out of band release, bump the version in info.json
appropriately based on merged pull requests since the last release and run ./release-prep.sh
to update CHANGELOG.md
.
The Schedule Release Prep workflow runs every Thursday, but uses the current week number modulo 2 in order to determine if it is an odd or even week. If it is an even week (In other words bi-weekly), then for the list of repositories kickoff the Auto Release Prep workflow. In order to not create a "storm" of release prep pull requests all being open at once, it sleeps for a random interval between 1 and 5 minutes between each repository. A self-hosted
GitHub runner is used due to the random sleep interval, since GitHub hosted runners bill based on minutes.
Pre-requisites:
- The called workflow must have an Actions secret called
BOT_GITHUB_TOKEN
with the value being a GitHub token withrepo
permission, and the token be be SSO authorized for the puppetlabs GitHub organization. - The called repository should contain a
release-prep.sh
script that performs the appropriate preparation steps locally (For example, updatingGemfile.lock
, orpackage-lock.json
, etc. andCHANGELOG.md
). - The called repository should label pull requests appropriately in order to determine the appropriate next version bump.
The sections below list each reusable workflow with usage, inputs, outpus, etc..
For more information about reusable workflows see Reusing workflows
NOTE: Please ensure that any repositories using these workflows reference them by a major version tag, as opposed to the default branch. Dependabot is able to detect updated tags for reusable workflows. This prevents breaking changes in the called workflows from breaking all caller workflows until the needed changes have been addressed.
Many of our tools follow Semantic Versioning, which means that applying one or more appropriate labels to pull requests is crucial both for determining the next release version of a tool and automatically generating an accurate changelog and release notes using github-changelog-generator.
The Auto Release Prep workflow finds pull requests that have been merged since the last release and determines the appropriate next version bump based on those pull request labels. Next, it updates the semantic version in the file provided by version-file-path
, commits and pushes to a new branch, then opens a pull request with the maintenance label.
Pre-requisites:
- The caller workflow must have an Actions secret called
BOT_GITHUB_TOKEN
with the value being a GitHub token withrepo
permission, and the token be be SSO authorized for the puppetlabs GitHub organization. - The caller repository should contain a
release-prep.sh
script that performs the appropriate preparation steps locally (For example, updatingGemfile.lock
, orpackage-lock.json
, etc. andCHANGELOG.md
). - The caller repository should label pull requests appropriately in order to determine the appropriate next version bump.
name: Automated release prep
on:
workflow_dispatch:
jobs:
release_prep:
uses: puppetlabs/release-engineering-repo-standards/.github/workflows/auto_release_prep.yml@v1
secrets: inherit
with:
project-type: ruby
version-file-path: lib/always_be_scheduling/version.rb
name: Automated release prep
on:
workflow_dispatch:
jobs:
release_prep:
uses: puppetlabs/release-engineering-repo-standards/.github/workflows/auto_release_prep.yml@v1
secrets: inherit
with:
project-type: npm
version-file-path: package.json
Secret name | Type | Description | Required |
---|---|---|---|
BOT_GITHUB_TOKEN | string | The token used to git push and open a pull request. | true |
Input name | Type | Description | Required | Default value |
---|---|---|---|---|
project-type | string | The project type used to determine how to perform a version bump. One of npm or ruby. | true | ruby |
version-file-path | string | The path to a file containing a semantic version to update. | true | None |
None
The Dependabot auto-merge workflow contains jobs used to gather the metadata of a pull request opened by Dependabot, then based on a condition, the pull request is approved and auto-merge enabled, meaning that as soon as all required status checks pass, then the pull request will automatically be merged. The workflow will also label "patch" dependency bumps with the "bug" label, and "minor" dependency bumps with the "enhancement" label.
Pre-requisites:
- The caller workflow must have an Actions secret called
BOT_GITHUB_TOKEN
with the value being a GitHub token withrepo
permission, and the token be be SSO authorized for the puppetlabs GitHub organization. - The caller repository must have the auto-merge setting enabled at Settings --> General --> Check "Allow auto-merge".
- The caller repository should have a branch protection rule with at least at least one check in the required status check to pass before merging.
- If the caller repository requires pull request reviews before merging, then the bot account associated with the token used for the
BOT_GITHUB_TOKEN
secret should be, or a member of a team used, in theCODEOWNERS
.
name: Dependabot auto-merge
on: pull_request
jobs:
dependabot_merge:
uses: puppetlabs/release-engineering-repo-standards/.github/workflows/dependabot_merge.yml@v1
secrets: inherit
with:
merge-if-minor-or-patch-update: true
Secret name | Type | Description | Required |
---|---|---|---|
BOT_GITHUB_TOKEN | string | The token used to approve and enable auto-merge on a pull request. | true |
Input name | Type | Description | Required | Default value |
---|---|---|---|---|
merge-if-minor-or-patch-update | boolean | Approve and enable auto-merge on the pull request if the dependency update is a minor or patch version bump. | false | true |
None
The Ensure label workflow ensures that at least one label exists on a pull request. If the check fails due to no labels existing, then simply add the appropriate label, and rerun the failed check
name: Ensure label
on: pull_request
jobs:
label_exists:
uses: puppetlabs/release-engineering-repo-standards/.github/workflows/ensure_label.yml@v1
None
None
None
Submit changes by opening a pull request and assigning the appropriate label.