TOML Action

• Features
  • Upcoming
• Comparison
• Inputs
• Outputs
• Tags
• Support
• Contributing

TOML 1.1.0 Action to Parse, Read or Edit Values using JSONPath and set the Results to Outputs or Write to a File.

This action was built from the ground up using active libraries. See the Comparison for more details.

Uses smol-toml for TOML 1.1.0 parsing and jsonpath-plus for JSONPath.

View Example TOML File

title = "TOML Example"

[project]
name = "toml-action"
dynamic = ["version"]
authors = [{ name="Shane" }]

Get a Value

- name: TOML Action
  id: toml
  uses: cssnr/toml-action@v1
  with:
    file: .github/test/test.toml
    path: $.project.authors[0].name

- name: Echo Value
  run: |
    echo "${{ steps.toml.outputs.value }}"

Results: Shane

Edit a Value

- name: TOML Action
  uses: cssnr/toml-action@v1
  with:
    file: .github/test/test.toml
    path: $.project.authors[0].name
    value: I Made This

- name: Cat File
  run: |
    cat ".github/test/test.toml"

Results: click to view

title = "TOML Example"

[project]
name = "toml-action"
dynamic = [ "version" ]

[[project.authors]]
name = "I Made This"

Note: the results are different from the source, but the structure is identical.

Parse a File

- name: TOML Action
  id: toml
  uses: cssnr/toml-action@v1
  with:
    file: .github/test/test.toml

- name: Echo Results
  run: |
    echo "name: ${{ fromJSON(steps.toml.outputs.data).project.name }}"
    echo "data: ${{ fromJSON(steps.toml.outputs.data) }}"

Results name: toml-action

Results data: click to view

{
  "title": "TOML Example",
  "project": {
    "name": "toml-action",
    "dynamic": ["version"],
    "authors": [
      {
        "name": "Shane"
      }
    ]
  }
}

See the Inputs for more options...

Features

• Use JSONPath
• Parse TOML File
• Read TOML Value
• Edit TOML Value
• Append to Array
• Write the Results
• Output Parsed Value
• Output JSON Results
• Output TOML Results

Upcoming

• Convert Input File/JSON/YAML to TOML
• Add Input to Set the type for value

Tip

Please submit a Feature Request to let us know what you want to see...

Comparison

Most of these actions are forks/clones of each other and none of them support JSONPath or both Read and Write.

Repository	Read	Write	Path	TOML Version	TOML Parser	Stars	Last Updated	Repository Language
cssnr/toml-action	✅	✅	✅	1.1.0	smol-toml
SebRollen/toml-action	✅	❌	❌	1.0.0-rc.1	iarna/toml
ciiiii/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml
colt-1/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml
rahulp959/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml
kaachod/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml
sandstromviktor/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml
dangdennis/toml-action	✅	❌	❌	0.4.0	toml
sebasptsch/toml-edit-action	❌	✅	❌	1.0.0	smol-toml
Larry-Le/toml-editor	❌	✅	❌	1.0.0-rc.1	iarna/toml

Inputs

Input	Default Value	Description of Input
file	Required	TOML File Path
path	-	JSONPath to Read or Edit
value	-	Value to Edit/Update
append	false	Append Value to Array
write	true	Write Updates to file
output	file	Write to a Different File

file

This is the TOML file path to process relative to the working directory.

path

A JSONPath key to read or edit.

This is a jsonpath-plus path and supports bare selectors project.version.

Leaving this blank will only read the file and output the JSON/TOML results.

• String key: $.key
• Nested key: $.key.nested
• Array key: $.key.nested[0]
• Quoted key: $['key with spaces'] (single or double quotes)

value

Value to edit/update at the given path. Non-existent paths are automatically created.

• Creating a path only supports plain keys and indices ($.a.b[0]); JSONPath query syntax (recursive descent $.., filters, wildcards, slices) cannot be used.
• All inputs are strings, but value is parsed with JSON.parse() into a string, boolean or number.
• Leading and trailing whitespace in value is preserved and written as-is.
• Integers larger than 2^53 are rounded and serialized as floats (e.g. 9007199254740993 is written as 9007199254740992.0).
• Leaving value blank only reads the value from path and outputs the results.
• To set an empty string, use the JSON-encoded form "" (e.g. value: '""'), since a blank value is treated as read mode.

append

When true, appends the value to an existing array at the path.

• If the path points to an existing array: the value is pushed onto the array.
• If the path does not exist: an array is created with the value as its single element.
• If the path points to an existing non-array value: the value is converted to an array and the new value is appended.

Default: false

Append to existing array:

- name: TOML Action
  uses: cssnr/toml-action@v1
  with:
    file: file.toml
    path: $.project.dynamic
    value: new-tag
    append: true

Given a file with dynamic = ["version"], this produces dynamic = ["version", "new-tag"].

Create array and append:

- name: TOML Action
  uses: cssnr/toml-action@v1
  with:
    file: file.toml
    path: $.project.tags
    value: stable
    append: true

If tags does not exist, this creates tags = ["stable"].

write

Write the results with the value back to the file.

To write to a different file, set the output to the file path.

Default: true

output

To write the results to a different file set the path to the file here. Directories will be created as necessary.

Default: file

Outputs

Output	Description
value	Parsed Value from Path (empty when created)
data	JSON Data
toml	TOML String

Note: All outputs are strings parsed with JSON.stringify().

Note: The value output is empty when the path does not exist in the file and a new key is created. Read the created value back from the data output (fromJSON(...)) in that case.

- name: TOML Action
  id: toml
  uses: cssnr/toml-action@v1
  with:
    file: file.toml
    path: author.name

- name: Echo Outputs
  env:
    toml: ${{ steps.toml.outputs.toml }}
  run: |
    echo "value: ${{ steps.toml.outputs.value }}"
    echo "data: ${{ steps.toml.outputs.data }}"
    echo "toml: ${toml}"

Note: toml is first set as an env variable due to the way multi-line output is evaluated using ${{ }} in a run block.

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Support

For general help or to request a feature, see:

• Q&A Discussion: https://github.com/cssnr/toml-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/toml-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results, you can:

• Report an Issue: https://github.com/cssnr/toml-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

For more information, see the CSSNR SUPPORT.md.

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• Actions Up Action
• Zensical Action
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• TOML Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• javascript-action - JavaScript
• typescript-action - TypeScript
• py-test-action - Dockerfile Python
• test-action-uv - Dockerfile Python UV
• docker-test-action - Docker Image Python

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/