|
| 1 | +Go API |
| 2 | +====== |
| 3 | +[![API Document][api-badge]][apidoc] |
| 4 | + |
| 5 | +This document describes how to use [actionlint](..) as Go library. |
| 6 | + |
| 7 | +actionlint can be used from Go programs by importing the module. |
| 8 | + |
| 9 | +```go |
| 10 | +import "github.com/rhysd/actionlint" |
| 11 | +``` |
| 12 | + |
| 13 | +See [the documentation][apidoc] to know the list of all APIs. It contains |
| 14 | +a workflow file parser built on top of `go-yaml/yaml`, expression `${{ }}` lexer/parser/checker, etc. |
| 15 | + |
| 16 | +Followings are unexhaustive list of interesting APIs. |
| 17 | + |
| 18 | +- `Command` struct represents entire `actionlint` command. `Command.Main` takes command line arguments and runs command |
| 19 | + until the end and returns exit status. |
| 20 | +- `Linter` manages linter lifecycle and applies checks to given files. If you want to run actionlint checks in your |
| 21 | + program, please use this struct. |
| 22 | +- `Project` and `Projects` detect a project (Git repository) in a given directory path and find configuration in it. |
| 23 | +- `Config` represents structure of `actionlint.yaml` config file. It can be decoded by [go-yaml/yaml][go-yaml] library. |
| 24 | +- `Workflow`, `Job`, `Step`, ... are nodes of workflow syntax tree. `Workflow` is a root node. |
| 25 | +- `Parse()` parses given contents into a workflow syntax tree. It tries to find syntax errors as much as possible and |
| 26 | + returns found errors as slice. |
| 27 | +- `Pass` is a visitor to traverse a workflow syntax tree. Multiple passes can be applied at single pass using `Visitor`. |
| 28 | +- `Rule` is an interface for rule checkers and `RuneBase` is a base struct to implement a rule checker. |
| 29 | + - `RuleExpression` is a rule checker to check expression syntax in `${{ }}`. |
| 30 | + - `RuleShellcheck` is a rule checker to apply `shellcheck` command to `run:` sections and collect errors from it. |
| 31 | + - `RuleJobNeeds` is a rule checker to check dependencies in `needs:` section. It can detect cyclic dependencies. |
| 32 | + - ... |
| 33 | +- `ExprLexer` lexes expression syntax in `${{ }}` and returns slice of `Token`. |
| 34 | +- `ExprParser` parses given slice of `Token` and returns syntax tree for expression in `${{ }}`. `ExprNode` is an |
| 35 | + interface for nodes in the expression syntax tree. |
| 36 | +- `ExprType` is an interface of types in expression syntax `${{ }}`. `ObjectType`, `ArrayType`, `StringType`, |
| 37 | + `NumberType`, ... are structs to represent actual types of expression. |
| 38 | +- `ExprSemanticsChecker` checks semantics of expression syntax `${{ }}`. It traverses given expression syntax tree and |
| 39 | + deduces its type, checking types and resolving variables (contexts). |
| 40 | +- `ValidateRefGlob()` and `ValidatePathGlob()` validate [glob filter pattern][filter-pattern-doc] and returns all errors |
| 41 | + found by the validator. |
| 42 | +- `ActionMetadata` is a struct for action metadata file (`action.yml`). It is used to check inputs specified at `with:` |
| 43 | + and typing `steps.{id}.outputs` object strictly. |
| 44 | +- `PopularActions` global variable is the data set of popular actions' metadata collected by [the script](../scripts/generate-popular-actions). |
| 45 | +- `AllWebhookTypes` global variable is the mapping from all webhook names to their types collected by [the script](../scripts/generate-webhook-events). |
| 46 | +- `WorkflowKeyAvailability()` returns available context names and special function names for the given workflow key like |
| 47 | + `jobs.<job_id>.outputs.<output_id>`. This function uses the data collected by [the script](../scripts/generate-availability). |
| 48 | + |
| 49 | +## Library versioning |
| 50 | + |
| 51 | +The version of this repository is for command line tool `actionlint`. So it does not represent the version of the library. |
| 52 | +It means that the library does not follow semantic versioning and any patch version bump may introduce some breaking changes. |
| 53 | + |
| 54 | +## Go version compatibility |
| 55 | + |
| 56 | +Minimum supported Go version is written in [`go.mod`](../go.mod) file in this repository. That said, older Go versions are |
| 57 | +actually not tested on CI. Last two major Go versions are recommended because they're tested on CI. For example, when the latest |
| 58 | +Go version is v1.22, v1.21 and v1.22 are nice to use. |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +[Checks](checks.md) | [Installation](install.md) | [Usage](usage.md) | [Configuration](config.md) | [References](reference.md) |
| 63 | + |
| 64 | +[api-badge]: https://pkg.go.dev/badge/github.com/rhysd/actionlint.svg |
| 65 | +[apidoc]: https://pkg.go.dev/github.com/rhysd/actionlint |
| 66 | +[go-yaml]: https://github.com/go-yaml/yaml |
| 67 | +[filter-pattern-doc]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet |
0 commit comments