README
¶
The GitHub Actions Workflow Parser
This is the language specification and the official parser
for GitHub Actions main.workflow files. It is running in
production as part of GitHub Actions. It is written in Go.
There are syntax-highlighting configuration files for Vim and Atom, under
the syntax/ directory.
Using the parser
To use the parser in your own projects, import it, and call the Parse
function.
import "github.com/actions/workflow-parser/parser"
...
config, err := parser.Parse(reader)
By default, the Parse function validates basic syntax, type safety, and
all dependencies within a .workflow file. It returns a model with
arrays of all workflows and actions defined in the file.
If there are any errors, Parse returns an error. System errors are
returned as a generic error class, while problems in the file are
returned as a parser.Error. The parser.Error struct has an array of
errors, each indicating a severity and a position in the file.
Warnings indicate code that might get ignored or misinterpreted. Errors
indicate code that is incomplete or has type errors and cannot run. Fatal
errors indicate that the file cannot be even partially displayed, due to a
syntax error or circular dependency. Only .workflow files with no
warnings, errors, or fatal errors will work with Actions.
To suppress warnings or non-fatal errors, use either of the following
functions as an optional second argument to Parse:
config, err := parser.Parse(reader, parser.WithSuppressWarnings())
// or
config, err := parser.Parse(reader, parser.WithSuppressErrors())
Developing the parser
You'll need a copy of go v1.9 or higher. You might also want a copy of
dep, if you plan to change Gopkg.toml.
On OS X, brew install go dep will get you there.
You can also use docker run -it golang on any Docker-compatible platform
to get a copy of Go. That doesn't include dep.
To run the tests and build a command-line binary that validates workflow
files, run make. The resulting validation binary works like so:
$ ./cmd/parser samples/a.workflow
samples/a.workflow is a valid file with 9 actions and 1 workflow
If you would like to contribute your work back to the project, please see
CONTRIBUTING.md.
License
This project is open source, under the MIT license.
Releases
Active development happens on the master branch. Releases happen by
tagging commits with vX.Y.Z, according to semantic
versioning. Increment the major version number
for:
- Changes to the parser implementation that will break code application code.
- Changes to the language spec that will reject existing, previously valid
.workflowfiles. If possible, use the top-levelversion=keyword to provide backward compatibility for existing files.
Increment the minor version number for:
- New language features that prior versions of the parser would have rejected.
Directories