# :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 <input-workflow-with-includes> <output-workflow-flattened>
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`).
Raw data
{
"_id": null,
"home_page": "https://github.com/mithro/actions-includes",
"name": "actions-includes",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Tim 'mithro' Ansell",
"author_email": "tansell@google.com",
"download_url": "https://files.pythonhosted.org/packages/61/9f/ba4db88e3de593eb1f324d4a0e4b37eca8c8f3144a2d649538c54d142fdd/actions-includes-0.0.post140.tar.gz",
"platform": null,
"description": "\n# :warning: This project is **mostly** abandoned.\n\nYou are probably better using\n[Composite Actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action)\nor\n[Reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows).\n\n--------------------------------\n--------------------------------\n\n# actions-includes\n\n[](https://github.com/mithro/actions-includes/blob/master/LICENSE)\n[](https://github.com/mithro/actions-includes/issues)\n\n\n\n\n\nAllows including an action inside another action (by preprocessing the YAML file).\n\nInstead of using `uses` or `run` in your action step, use the keyword `includes`.\n\nOnce you are using the `includes` argument, the workflows can be expanded using this tool as follows:\n```sh\n# python -m actions_include <input-workflow-with-includes> <output-workflow-flattened>\n\npython -m actions_includes ./.github/workflows-src/workflow-a.yml ./.github/workflows/workflow-a.yml\n```\n\n## Usage with docker\n\n```sh\ndocker 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\n```\n\n## `includes:` step\n\n```yaml\n\nsteps:\n- name: Other step\n run: |\n command\n\n- includes: {action-name}\n with:\n {inputs}\n\n- name: Other step\n run: |\n command\n```\n\nThe `{action-name}` follows the same syntax as the standard GitHub action\n[`uses`](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsuses)\nand the action referenced should look exactly like a\n[GitHub \"composite action\"](https://docs.github.com/en/actions/creating-actions/creating-a-composite-run-steps-action)\n**except** `runs.using` should be `includes`.\n\nFor example;\n - `{owner}/{repo}@{ref}` - Public action in `github.com/{owner}/{repo}`\n - `{owner}/{repo}/{path}@{ref}` - Public action under `{path}` in\n `github.com/{owner}/{repo}`.\n - `./{path}` - Local action under local `{path}`, IE `./.github/actions/{action-name}`.\n\nAs it only makes sense to reference composite actions, the `docker://` form isn't supported.\n\nAs you frequently want to include local actions, `actions-includes` extends the \n`{action-name}` syntax to also support:\n\n - `/{name}` - Local action under `./.github/includes/actions/{name}`.\n\nThis is how composite actions should have worked.\n\n## `includes-script:`\nYou can include a script (e.g., a Python or shell script) in your workflow.yml file using the `includes-script` step.\n\nExample script file: `script.py`\n> ```python\n> print('Hello world')\n> ```\n\nTo include the script, reference it in an `includes-script` action in your `workflow.yml`, like so:\n> ```yaml\n> steps:\n> - name: Other step\n> run: |\n> command\n>\n> - name: Hello\n> includes-script: script.py\n>\n> - name: Other step\n> run: |\n> command\n> ```\n\nWhen the workflow.yml is processed by running\n```python -m actions_includes.py workflow.in.yml workflow.out.yml```,\nthe resultant `workflow.out.yml` looks like this:\n> ```yaml\n> steps:\n> - name: Other step\n> run: |\n> command\n> \n> - name: Hello\n> shell: python\n> run: |\n> print('Hello world')\n> \n> - name: Other step\n> run: |\n> command\n> ```\nThe `shell` parameter is deduced from the file extension, \nbut it is possible to use a custom shell by setting the \n`shell` parameter manually.\n\n## Using a pre-commit hook\nWhen you use actions-includes, it may be useful to add a pre-commit hook \n(see https://git-scm.com/docs/githooks) to your project so that your workflow \nfiles are always pre-processed before they reach GitHub. \n\n### With a git hooks package\nThere are multiple packages (notably `pre-commit`; \nsee https://pre-commit.com/) that support adding pre-commit hooks.\n\nIn the case of using the `pre-commit` package, you can add an entry \nsuch as the following to your `pre-commit-config.yaml` file:\n> ```\n> - repo: local\n> hooks:\n> - id: preprocess-workflows\n> name: Preprocess workflow.yml\n> entry: python -m actions_includes.py workflow.in.yml workflow.out.yml\n> language: system\n> always-run: true\n> ```\n\n### Without a git hooks package\nAlternatively, to add a pre-commit hook without installing another \npackage, you can simply create or modify `.git/hooks/pre-commit`\n(relative to your project root). A sample file typically \nlives at `.git/hooks/pre-commit.sample`.\n\nThe pre-commit hook should run the commands that are necessary to \npre-process your workflows. So, your `.git/hooks/pre-commit` file \nmight look something like this:\n> ```sh\n> #!/bin/bash\n>\n> python -m actions_includes.py workflow.in.yml workflow.out.yml || {\n> echo \"Failed to preprocess workflow file.\"\"\"\n> }\n> ```\n\nTo track this script in source code management, you'll have to\nput it in a non-ignored file in your project that is then copied to \n`.git/hooks/pre-commit` as part of your project setup. See\nhttps://github.com/ModularHistory/modularhistory for an example\nof a project that does this with a setup script (`setup.sh`).\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Tool for flattening include statements in GitHub actions workflow.yml files.",
"version": "0.0.post140",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "47d189cf20c281dbd29ed78a64b2717cc1d011eb060b39970dd7116c1ea09730",
"md5": "cdfc90139889f9f436ff19ca5ff4da13",
"sha256": "4b3e0d8b897831ad862731b75e8f54308a73cdcef5ad696480fc9478831e2694"
},
"downloads": -1,
"filename": "actions_includes-0.0.post140-py3.8.egg",
"has_sig": false,
"md5_digest": "cdfc90139889f9f436ff19ca5ff4da13",
"packagetype": "bdist_egg",
"python_version": "0.0.post140",
"requires_python": ">=3.8",
"size": 57827,
"upload_time": "2023-01-19T22:04:51",
"upload_time_iso_8601": "2023-01-19T22:04:51.479838Z",
"url": "https://files.pythonhosted.org/packages/47/d1/89cf20c281dbd29ed78a64b2717cc1d011eb060b39970dd7116c1ea09730/actions_includes-0.0.post140-py3.8.egg",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "409ea9edf71a0de9053cc369959d2008542d9e41e4e06975de9ceec01ba0a7f2",
"md5": "9d288fffedb1d379f4cd988f129b889f",
"sha256": "2836b72c81b88c75b3a3f3283ccd97c4b608ad6410a88e257202741beebe24fb"
},
"downloads": -1,
"filename": "actions_includes-0.0.post140-py3.9.egg",
"has_sig": false,
"md5_digest": "9d288fffedb1d379f4cd988f129b889f",
"packagetype": "bdist_egg",
"python_version": "0.0.post140",
"requires_python": ">=3.8",
"size": 57806,
"upload_time": "2023-01-19T22:04:51",
"upload_time_iso_8601": "2023-01-19T22:04:51.407500Z",
"url": "https://files.pythonhosted.org/packages/40/9e/a9edf71a0de9053cc369959d2008542d9e41e4e06975de9ceec01ba0a7f2/actions_includes-0.0.post140-py3.9.egg",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d47387a737967c37989c085fb9fc2830ceb5156e5585c6ff06f16889fd0a79a",
"md5": "99cc2c957758b3f6b853bc02a295a7ea",
"sha256": "3b2e06f524b3d89318894cee725eb3a0e272fbf24f0a1511f8a2455116a81ce6"
},
"downloads": -1,
"filename": "actions_includes-0.0.post140-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99cc2c957758b3f6b853bc02a295a7ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31275,
"upload_time": "2023-01-19T22:04:48",
"upload_time_iso_8601": "2023-01-19T22:04:48.950715Z",
"url": "https://files.pythonhosted.org/packages/7d/47/387a737967c37989c085fb9fc2830ceb5156e5585c6ff06f16889fd0a79a/actions_includes-0.0.post140-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "619fba4db88e3de593eb1f324d4a0e4b37eca8c8f3144a2d649538c54d142fdd",
"md5": "58030b5350fb115391a4d58b9827dc7f",
"sha256": "ae286cc068da436b8eccd6dd1f8a1ec9849533fa14cdb54a87f5212adde9e023"
},
"downloads": -1,
"filename": "actions-includes-0.0.post140.tar.gz",
"has_sig": false,
"md5_digest": "58030b5350fb115391a4d58b9827dc7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39348,
"upload_time": "2023-01-19T22:04:50",
"upload_time_iso_8601": "2023-01-19T22:04:50.446221Z",
"url": "https://files.pythonhosted.org/packages/61/9f/ba4db88e3de593eb1f324d4a0e4b37eca8c8f3144a2d649538c54d142fdd/actions-includes-0.0.post140.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-19 22:04:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mithro",
"github_project": "actions-includes",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "actions-includes"
}
JSON
