https://github.com/zakodium/workflows
Shared reusable GitHub workflows
https://github.com/zakodium/workflows
tools
Last synced: 5 months ago
JSON representation
Shared reusable GitHub workflows
- Host: GitHub
- URL: https://github.com/zakodium/workflows
- Owner: zakodium
- License: mit
- Created: 2021-10-16T08:20:12.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-09-24T09:02:34.000Z (9 months ago)
- Last Synced: 2025-10-20T10:41:51.679Z (8 months ago)
- Topics: tools
- Homepage:
- Size: 85 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# workflows
Shared reusable GitHub workflows.
## Available workflows
* [`nodejs` (Node.js CI)](#nodejs-ci)
* [`release`](#release)
* [`docker-image`](#docker-image)
* [`typedoc`](#typedoc)
* [`npm-prerelease`](#npm-prerelease)
### Node.js CI
Generic workflow to run linters and tests for Node.js projects. It supports `eslint`,
`prettier`, and `check-types` linter steps, will run tests using a matrix of
Node.js versions, and verify that the package can be published to a registry
and imported.
#### Inputs
* **node-version**:
* Version of Node.js used to run the lint steps.
* Default: `24.x`
* **npm-setup-command**:
* Command used to set up the package before running other steps.
* Default: `npm ci` if there is a `package-lock.json`, `npm install` otherwise.
* **lint-eslint**:
* Whether to run the `eslint` npm script.
* Default: `true`
* **lint-prettier**:
* Whether to run the `prettier` npm script.
* Default: `true`
* **lint-check-types**:
* Whether to run the `check-types` npm script. This should be set to `true`
for TypeScript projects.
* Default: `false`
* **disable-tests**:
* Disable the test matrix.
* Default: `false`
* **disable-test-package**:
* Disable testing that the package can safely be published to a registry
and imported.
* Default: `false`
* **node-version-matrix**:
* Versions of Node.js to test on, as a JSON array.
* Default: `'[20, 22, 24, 25]'`
* **test-setup-command**:
* Command used to set up the package before running npm tests.
Will run between `npm-setup-command` and `npm-test-command`.
* Default: `undefined`
* **npm-test-command**:
* Command used to run the tests.
* Default: `npm run test-only`
* **upload-coverage**:
* Whether to run the Codecov action to upload coverage data.
This requires to pass the `codecov-token` secret for private repos.
* Default: `true` for public repos and `false` for private repos.
* **cwd**:
* Usefully for monorepos. Set the working directory to run the steps in.
* Default: `.`.
#### Secrets
* **codecov-token**
A token for code coverage uploads.
Necessary for private repos and public repos if the organization hasn't enabled [tokenless uploads](https://docs.codecov.com/docs/codecov-tokens#uploading-without-a-token).
* **env**
Environment variables necessary to run the tests.
Must be passed with the `KEY=value` format (one per line).
Values will be automatically treated as secrets and redacted from the logs.
#### Example usage for a TypeScript project
```yml
name: Node.js CI
on:
push:
branches:
- main
pull_request:
jobs:
nodejs:
# Documentation: https://github.com/zakodium/workflows#nodejs-ci
uses: zakodium/workflows/.github/workflows/nodejs.yml@nodejs-v1
with:
lint-check-types: true
```
### Release
The release workflow helps to automatically release packages that conform to the
[conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
It uses the [Release Please Action](https://github.com/google-github-actions/release-please-action#release-please-action)
to maintain a release pull request. When the pull request is merged, the changelog
is updated and a release is created in GitHub. Additionally, it is possible to
publish the package to the npm and GitHub package registries.
#### Inputs
* **github-app-id**
* The id of a GitHub app used to publish the release.
The `github-app-key` secret is mandatory when this is set.
* **npm**:
* Pass `true` to enable the npm publish steps. In that case, the `npm-token`
or `github-token` (or both) secret is mandatory.
* Default: `false`
* **node-version**:
* Version of Node.js used to run the npm publish steps.
* Default: `24.x`
* **npm-setup-command**:
* Command used to set up the package before publishing to npm.
* Default: `npm ci` if there is a `package-lock.json`, `npm install` otherwise.
* **public**:
* This option only affects scoped packages.
Whether the package will be published to the public npm registry. If `false`,
the package will be published only to the GitHub Package Registry (GPR).
When publishing to GPR, the `github-token` must have the `packages: write` permission.
* Default: `false`
* **release-type**:
* Option passed to the [release-please action](https://github.com/googleapis/release-please-action?tab=readme-ov-file#release-types-supported).
Set to the empty string to use a [release manifest config](https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md).
* Default: `node`
#### Secrets
* **github-app-key**
A GitHub app private key belonging to the app referenced by `github-app-id`.
Mandatory when `github-app-id` is passed.
* **github-token**
A GitHub token passed to release-please (if not using `github-app-key`) and npm (if the package is published to GPR).
* **npm-token**
A npm automation token with the permission to publish this package.
#### Example usages
##### With a GitHub app - package released to GPR
````yml
name: Release
on:
push:
branches:
- main
jobs:
release:
# Documentation: https://github.com/zakodium/workflows#release
uses: zakodium/workflows/.github/workflows/release.yml@release-v1
permissions:
packages: write
with:
npm: true
public: false
github-app-id: ${{ vars.RELEASE_APP_ID }}
secrets:
github-app-key: ${{ secrets.RELEASE_APP_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
````
##### With a GitHub app - repository not published to a registry
````yml
name: Release
on:
push:
branches:
- main
jobs:
release:
# Documentation: https://github.com/zakodium/workflows#release
uses: zakodium/workflows/.github/workflows/release.yml@release-v1
with:
github-app-id: ${{ vars.RELEASE_APP_ID }}
secrets:
github-app-key: ${{ secrets.RELEASE_APP_KEY }}
````
##### With a GitHub PAT - package released to the public npm registry
````yml
name: Release
on:
push:
branches:
- main
jobs:
release:
# Documentation: https://github.com/zakodium/workflows#release
uses: zakodium/workflows/.github/workflows/release.yml@release-v1
with:
npm: true
secrets:
github-token: ${{ secrets.BOT_TOKEN }}
npm-token: ${{ secrets.NPM_BOT_TOKEN }}
````
### Docker image
This workflow allows to build and push a Docker image to some registry. It can handle simple explicit tags and releases.
#### Inputs
* **dockerfile**
* Path to the Dockerfile to build.
* Default: `Dockerfile`
* **registry**
* Hostname for the Docker registry.
* Default: `ghcr.io`
* **registry-user**
* Username to log in to the registry.
* Default: `${{ github.actor }}`
* **image-name**
* Name of the Docker image. E.g. `zakodium/workflows`
* Default: `${{ github.repository }}`
* **tag**
* Name of the tag to push. Ignored if `tag-version` is passed.
* Default: `HEAD`
* **tag-version**
* Semver version to use as a tag (v prefix is optional). E.g. `v1.2.3`.
It will automatically be split to publish three versions. E.g. `1.2.3`, `1.2`, `1`.
* **tag-latest**
* Whether a `latest` tag should be published as well.
* Default: `true` if `tag-version` is passed, `false` otherwise.
* **cwd**:
* Set the working directory to run the Docker build in.
* Default: `.`
* **ref**:
* GitHub ref to checkout.
* Default: Ref that corresponds to the triggering event.
* **checkout-submodules**:
* Whether submodules should be initialized during checkout.
* Default `false`
#### Secrets
* **registry-token**
* Token for the Docker registry.
* Default: Job's `secret.GITHUB_TOKEN`.
#### Example usage
Publish an image to the GitHub package registry using the default job's token:
```yml
name: Docker Image CI
on:
workflow_dispatch:
inputs:
ref:
description: 'GitHub ref to checkout'
required: true
default: main
tag:
description: 'Docker tag to push (do NOT use "latest" or version numbers)'
required: true
default: 'HEAD'
push:
tags:
- v*
jobs:
docker-image:
# Documentation: https://github.com/zakodium/workflows#docker-image
uses: zakodium/workflows/.github/workflows/docker-image.yml@docker-image-v1
with:
ref: ${{ inputs.ref }}
tag: ${{ inputs.tag }}
tag-version: ${{ github.event_name == 'push' && github.ref_name || '' }}
```
### TypeDoc
The typedoc workflow can be used to generate a documentation website with [TypeDoc](https://typedoc.org/)
and publish it to GitHub pages.
#### Inputs
* **entry**:
* Entry point of the API.
Multiple entry points can be specified using spaces as separators.
Defaults to `src/index.ts`.
* **name**:
* Name of the package. It will be used as a documentation title.
Defaults to `package.json`'s name field.
* **node-version**:
* Version of Node.js used to run the build steps.
* Default: `24.x`
* **npm-setup-command**:
* Command used to set up the package before publishing to npm.
* Default: `npm ci` if there is a `package-lock.json`, `npm install` otherwise.
#### Secrets
* **github-token**
Token used to deploy to GitHub pages.
#### Example usage
````yml
name: TypeDoc
on:
workflow_dispatch:
release:
types: [published]
jobs:
typedoc:
# Documentation: https://github.com/zakodium/workflows#typedoc
uses: zakodium/workflows/.github/workflows/typedoc.yml@typedoc-v1
with:
entry: 'src/index.ts'
secrets:
github-token: ${{ secrets.BOT_TOKEN }}
````
### npm prerelease
This workflow allows to create a npm pre-release.
The state of the repository will be published as-is, using `$currentVersion-pre-$epoch` as a version number
and `pre` as the npm dist-tag.
Scoped packages are not supported for security reasons.
#### Inputs
* **node-version**:
* Version of Node.js used to run the npm publish steps.
* Default: `24.x`
* **npm-setup-command**:
* Command used to set up the package before publishing to npm.
* Default: `npm ci` if there is a `package-lock.json`, `npm install` otherwise.
#### Example usage
````yml
name: Prerelease package on npm
on:
pull_request:
types: [labeled]
workflow_dispatch:
jobs:
prerelease:
# Documentation: https://github.com/zakodium/workflows#npm-prerelease
uses: zakodium/workflows/.github/workflows/npm-prerelease.yml@npm-prerelease-v1
secrets:
github-token: ${{ secrets.BOT_TOKEN }}
npm-token: ${{ secrets.NPM_BOT_TOKEN }}
````