This GitHub action can create DotSlash files for executables that you have published as part of a GitHub release. The newly generated DotSlash files will be added to the existing release.
This action is designed to run after the GitHub Actions workflows that are responsible for
uploading your primary release artifacts via gh release upload or equivalent.
If you had separate workflows for each platform such as linux-release,
macos-release, and windows-release, then you could define a new GitHub
action under .github/workflows/dotslash.yml as follows:
name: Generate DotSlash files
on:
workflow_run:
# These must match the names of the workflows that publish
# artifacts to your GitHub release.
workflows: [linux-release, macos-release, windows-release]
types:
- completed
jobs:
generate-dotslash-files:
name: Generating and uploading DotSlash files
runs-on: ubuntu-latest
if: $
steps:
- uses: facebook/dotslash-publish-release@v1
# This is necessary because the action uses
# `gh release upload` to publish the generated DotSlash file(s)
# as part of the release.
env:
GITHUB_TOKEN: $
with:
# Additional file that lives in your repo that defines
# how your DotSlash file(s) should be generated.
config: .github/workflows/dotslash-config.json
# Tag for the release to to target.
tag: $
Note the config line that specifies a path to a JSON file in your repo that
determines what DotSlash files to generate. For example, if this GitHub action
were defined in the facebook/hermes
repository on GitHub, and the contents of
.github/workflows/dotslash-config.json were as follows:
{
"outputs": {
"hermes": {
"platforms": {
"macos-x86_64": {
"regex": "^hermes-cli-darwin-",
"path": "hermes"
},
"macos-aarch64": {
"regex": "^hermes-cli-darwin-",
"path": "hermes"
},
"linux-x86_64": {
"regex": "^hermes-cli-linux-",
"path": "hermes"
},
"windows-x86_64": {
"regex": "^hermes-cli-windows-",
"path": "hermes.exe"
}
}
}
}
}
Then this action would have added the following DotSlash file named hermes to
the v0.12.0 release:
#!/usr/bin/env dotslash
{
"name": "hermes",
"platforms": {
"macos-x86_64": {
"size": 10600817,
"hash": "blake3",
"digest": "25f984911f199f9229ca0327c52700fa9a8db9aefe95e84f91ba6be69902436a",
"format": "tar.gz",
"path": "hermes",
"providers": [
{
"url": "https://github.com/facebook/hermes/releases/download/v0.12.0/hermes-cli-darwin-v0.12.0.tar.gz"
},
{
"type": "github-release",
"repo": "https://github.com/facebook/hermes",
"tag": "v0.12.0",
"name": "hermes-cli-darwin-v0.12.0.tar.gz"
}
]
},
"macos-aarch64": {
"size": 10600817,
"hash": "blake3",
"digest": "25f984911f199f9229ca0327c52700fa9a8db9aefe95e84f91ba6be69902436a",
"format": "tar.gz",
"path": "hermes",
"providers": [
{
"url": "https://github.com/facebook/hermes/releases/download/v0.12.0/hermes-cli-darwin-v0.12.0.tar.gz"
},
{
"type": "github-release",
"repo": "https://github.com/facebook/hermes",
"tag": "v0.12.0",
"name": "hermes-cli-darwin-v0.12.0.tar.gz"
}
]
},
"linux-x86_64": {
"size": 47099598,
"hash": "blake3",
"digest": "8d2c1bcefc2ce6e278167495810c2437e8050780ebb4da567811f1d754ad198c",
"format": "tar.gz",
"path": "hermes",
"providers": [
{
"url": "https://github.com/facebook/hermes/releases/download/v0.12.0/hermes-cli-linux-v0.12.0.tar.gz"
},
{
"type": "github-release",
"repo": "https://github.com/facebook/hermes",
"tag": "v0.12.0",
"name": "hermes-cli-linux-v0.12.0.tar.gz"
}
]
},
"windows-x86_64": {
"size": 17456100,
"hash": "blake3",
"digest": "7efee4f92a05e34ccfa7c21c7a05f939d8b724bc802423d618db22efb83bfe1b",
"format": "tar.gz",
"path": "hermes.exe",
"providers": [
{
"url": "https://github.com/facebook/hermes/releases/download/v0.12.0/hermes-cli-windows-v0.12.0.tar.gz"
},
{
"type": "github-release",
"repo": "https://github.com/facebook/hermes",
"tag": "v0.12.0",
"name": "hermes-cli-windows-v0.12.0.tar.gz"
}
]
}
}
}
Note that each entry in platforms in the dotslash-config.json is reflected
in the platforms section of the generated DotSlash file. Each config entry
takes a "name" or a "regex" to use to identify the appropriate artifact in
the release and the "path" indicates the "path" that should be used for the
artifact in the generated DotSlash file.
The dotslash-publish-release action defaults to using BLAKE3 as the hash
function, so it takes responsibility for computing the size and digest
values. It also tries to “guess” the appropriate value of "format" based on
the suffix of the URL, though this can also be specified explicitly, which is a
bit safer:
{
"outputs": {
"hermes": {
"platforms": {
"macos-x86_64": {
"regex": "^hermes-cli-darwin-",
"format": "tar.gz",
"path": "hermes"
},
...
By default, dotslash-publish-release generates both the HTTP provider as well
as the github-release provider for each entry in the DotSlash file. Either of
these can be disabled via top-level "exclude-http-provider" and
"exclude-github-release-provider" properties, respectively. For example, if
you are using this action in a private GitHub repo, then you probably want to
disable the HTTP provider:
{
"exclude-http-provider": true,
"outputs": {
"hermes": {
"platforms": {
"macos-x86_64": {
"regex": "^hermes-cli-darwin-",
"format": "tar.gz",
"path": "hermes"
},
...
The generated DotSlash file would reflect this change:
#!/usr/bin/env dotslash
{
"name": "hermes",
"platforms": {
"macos-x86_64": {
"size": 10600817,
"hash": "blake3",
"digest": "25f984911f199f9229ca0327c52700fa9a8db9aefe95e84f91ba6be69902436a",
"format": "zst",
"path": "hermes",
"providers": [
{
"type": "github-release",
"repo": "https://github.com/facebook/hermes",
"tag": "v0.12.0",
"name": "hermes-cli-darwin-v0.12.0.tar.gz"
}
]
},
...
The most important part of the config file is the top-level "outputs" entry.
Each key in this entry will be the name of the generated DotSlash file that is
added to the release.
The "platforms" map for each entry requires that the keys are platforms that
are recognized by DotSlash.
Each platform entry recognizes the following properties:
regex or name is required to identify the file in the release that
should be used as the DotSlash artifact for the platform.path is required and is used as the corresponding path value in the
DotSlash file.format is optional, but recommended. It must be a valid DotSlash artifact
format, such as
tar.gz. If the artifact is not compressed, then "format": null must be
specified explicitly in the config JSON.hash must be one of "blake3" or "sha256", but it defaults to "blake3",
so it is optional.This action supports the following inputs:
config (required): Path to .json file in the repo that defines how DotSlash files should be generated.tag (required): Tag identifying the release whose assets should be used.include-build-metadata (optional): Whether to include build metadata in the generated DotSlash files. Defaults to true.By default, the action embeds build metadata in the generated DotSlash files to provide traceability about how and when the files were generated. This metadata includes:
Example of embedded metadata:
{
"name": "my-tool",
"platforms": { ... },
"build_metadata": {
"source_config": ".github/workflows/dotslash-config.json",
"ci": {
"github_repository": "owner/repo",
"github_sha": "abc123def456",
"github_run_id": "987654321",
"github_workflow": "Build and Release",
"github_actor": "john-doe",
"github_event_name": "release",
"github_server_url": "https://github.com"
},
"generated_at": "2025-09-28T15:23:57.878282Z",
"ci_job_url": "https://github.com/owner/repo/actions/runs/987654321"
}
}
To disable build metadata inclusion, set include-build-metadata to false:
- uses: facebook/dotslash-publish-release@v1
with:
config: .github/workflows/dotslash-config.json
tag: $
include-build-metadata: false
dotslash-publish-release is MIT licensed.