TOML Action

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

TOML 1.0.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.0.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
• 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.0.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
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.

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]

value

Value to edit/update at the given path.

Note: All inputs are strings but value is parsed with JSON.parse() to a string, boolean or number.

Leaving this blank will only read the value from path and output the results.

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
data	JSON Data
toml	TOML String

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

- 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/