https://github.com/mithro/actions-includes
Allows including an action inside another action (by preprocessing the Yaml file). This is how composite actions should have worked.
https://github.com/mithro/actions-includes
Last synced: 11 months ago
JSON representation
Allows including an action inside another action (by preprocessing the Yaml file). This is how composite actions should have worked.
- Host: GitHub
- URL: https://github.com/mithro/actions-includes
- Owner: mithro
- License: apache-2.0
- Created: 2021-02-25T01:34:59.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-01-19T22:03:56.000Z (over 3 years ago)
- Last Synced: 2025-07-02T16:12:56.832Z (11 months ago)
- Language: Python
- Homepage:
- Size: 208 KB
- Stars: 72
- Watchers: 5
- Forks: 9
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# :warning: This project is **mostly** abandoned.
You are probably better using
[Composite Actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action)
or
[Reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
--------------------------------
--------------------------------
# actions-includes
[](https://github.com/mithro/actions-includes/blob/master/LICENSE)
[](https://github.com/mithro/actions-includes/issues)
Allows including an action inside another action (by preprocessing the YAML file).
Instead of using `uses` or `run` in your action step, use the keyword `includes`.
Once you are using the `includes` argument, the workflows can be expanded using this tool as follows:
```sh
# python -m actions_include
python -m actions_includes ./.github/workflows-src/workflow-a.yml ./.github/workflows/workflow-a.yml
```
## Usage with docker
```sh
docker container run --rm -it -v $(pwd):/github/workspace --entrypoint="" ghcr.io/mithro/actions-includes/image:main python -m actions_includes ./.github/workflows-src/workflow-a.yml ./.github/workflows/workflow-a.yml
```
## `includes:` step
```yaml
steps:
- name: Other step
run: |
command
- includes: {action-name}
with:
{inputs}
- name: Other step
run: |
command
```
The `{action-name}` follows the same syntax as the standard GitHub action
[`uses`](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsuses)
and the action referenced should look exactly like a
[GitHub "composite action"](https://docs.github.com/en/actions/creating-actions/creating-a-composite-run-steps-action)
**except** `runs.using` should be `includes`.
For example;
- `{owner}/{repo}@{ref}` - Public action in `github.com/{owner}/{repo}`
- `{owner}/{repo}/{path}@{ref}` - Public action under `{path}` in
`github.com/{owner}/{repo}`.
- `./{path}` - Local action under local `{path}`, IE `./.github/actions/{action-name}`.
As it only makes sense to reference composite actions, the `docker://` form isn't supported.
As you frequently want to include local actions, `actions-includes` extends the
`{action-name}` syntax to also support:
- `/{name}` - Local action under `./.github/includes/actions/{name}`.
This is how composite actions should have worked.
## `includes-script:`
You can include a script (e.g., a Python or shell script) in your workflow.yml file using the `includes-script` step.
Example script file: `script.py`
> ```python
> print('Hello world')
> ```
To include the script, reference it in an `includes-script` action in your `workflow.yml`, like so:
> ```yaml
> steps:
> - name: Other step
> run: |
> command
>
> - name: Hello
> includes-script: script.py
>
> - name: Other step
> run: |
> command
> ```
When the workflow.yml is processed by running
```python -m actions_includes.py workflow.in.yml workflow.out.yml```,
the resultant `workflow.out.yml` looks like this:
> ```yaml
> steps:
> - name: Other step
> run: |
> command
>
> - name: Hello
> shell: python
> run: |
> print('Hello world')
>
> - name: Other step
> run: |
> command
> ```
The `shell` parameter is deduced from the file extension,
but it is possible to use a custom shell by setting the
`shell` parameter manually.
## Using a pre-commit hook
When you use actions-includes, it may be useful to add a pre-commit hook
(see https://git-scm.com/docs/githooks) to your project so that your workflow
files are always pre-processed before they reach GitHub.
### With a git hooks package
There are multiple packages (notably `pre-commit`;
see https://pre-commit.com/) that support adding pre-commit hooks.
In the case of using the `pre-commit` package, you can add an entry
such as the following to your `pre-commit-config.yaml` file:
> ```
> - repo: local
> hooks:
> - id: preprocess-workflows
> name: Preprocess workflow.yml
> entry: python -m actions_includes.py workflow.in.yml workflow.out.yml
> language: system
> always-run: true
> ```
### Without a git hooks package
Alternatively, to add a pre-commit hook without installing another
package, you can simply create or modify `.git/hooks/pre-commit`
(relative to your project root). A sample file typically
lives at `.git/hooks/pre-commit.sample`.
The pre-commit hook should run the commands that are necessary to
pre-process your workflows. So, your `.git/hooks/pre-commit` file
might look something like this:
> ```sh
> #!/bin/bash
>
> python -m actions_includes.py workflow.in.yml workflow.out.yml || {
> echo "Failed to preprocess workflow file."""
> }
> ```
To track this script in source code management, you'll have to
put it in a non-ignored file in your project that is then copied to
`.git/hooks/pre-commit` as part of your project setup. See
https://github.com/ModularHistory/modularhistory for an example
of a project that does this with a setup script (`setup.sh`).