The parser for GitHub Actions Workflow files
Branch: master
Clone or download
piki Merge pull request #26 from actions/ci2
Use the `golang-action` instead of a hand-rolled `cibuild` script
Latest commit 34f15fc Feb 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Merge pull request #26 from actions/ci2 Feb 9, 2019
cmd Make pe.Error() print all of pe.Errors Jan 31, 2019
model Move events to parser package and make internal Feb 1, 2019
parser Capitalize Parser consistently Feb 1, 2019
samples Add a sample with syntax error Jan 27, 2019
syntax Add syntax-highlighting files Jan 19, 2019
vendor/github.com
.gitignore Import the parser Jan 18, 2019
CODE_OF_CONDUCT.md Add CODE_OF_CONDUCT.md Jan 31, 2019
CONTRIBUTING.md Fix broken link Jan 31, 2019
Gopkg.lock Bump to the latest `actions/hcl` Feb 1, 2019
Gopkg.toml
LICENSE Initial commit Jan 18, 2019
Makefile Merge branch 'master' of https://github.com/github/actions-parser Jan 28, 2019
README.md Merge pull request #23 from actions/package-cleanups-and-renames Feb 1, 2019
language.md Fix: allow empty array Jan 29, 2019

README.md

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 .workflow files. If possible, use the top-level version= 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.