Tool for flattening include statements in GitHub actions workflow.yml files.
Project description
actions-includes
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:
# 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
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
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
and the action referenced should look exactly like a
GitHub "composite action"
except runs.using should be includes.
For example;
{owner}/{repo}@{ref}- Public action ingithub.com/{owner}/{repo}{owner}/{repo}/{path}@{ref}- Public action under{path}ingithub.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
print('Hello world')
To include the script, reference it in an includes-script action in your workflow.yml, like so:
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:
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:
#!/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).
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file actions-includes-0.0.post136.tar.gz.
File metadata
- Download URL: actions-includes-0.0.post136.tar.gz
- Upload date:
- Size: 39.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d57a6260bf470b7f0d92668ca4b3c5eb4f995cbad7d849e3dfc1ff7a4476afcd |
|
| MD5 | cfc7ada37762fbbd04c73aa1144e67aa |
|
| BLAKE2b-256 | 757dba75db0764b4a134567d7a6e471d8809c61f05742855c92a5a2fbf579904 |
File details
Details for the file actions_includes-0.0.post136-py3.9.egg.
File metadata
- Download URL: actions_includes-0.0.post136-py3.9.egg
- Upload date:
- Size: 57.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.9.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d6187c6c6c5978b52fbd17e02c06011232f88ed5d18e38ec884f58d4bf821337 |
|
| MD5 | 0ed21febb3e6234a73136ed0699d382e |
|
| BLAKE2b-256 | ef4dcb086471019f6c71f018561e4e35194b18cf8d194356bd6ff8ef6f00904c |
File details
Details for the file actions_includes-0.0.post136-py3.8.egg.
File metadata
- Download URL: actions_includes-0.0.post136-py3.8.egg
- Upload date:
- Size: 57.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7576fc3b94aa539fe7cb6e8eac6f58cedf01a7624ef980dbbf4da4b44b6cd163 |
|
| MD5 | 56c07992d8b43471f7e164b38f8df617 |
|
| BLAKE2b-256 | a290165147964bb58e3447b3cf581e1d4cef1cac508398b2dca8e5b45c2478c2 |
File details
Details for the file actions_includes-0.0.post136-py3-none-any.whl.
File metadata
- Download URL: actions_includes-0.0.post136-py3-none-any.whl
- Upload date:
- Size: 31.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/4.5.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.9.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0fb2d190f58617eea5e43a3b43ab2aefa9393d70cc47a04395f18e21a17cac57 |
|
| MD5 | b275cc35452ec87001252cd960e46bff |
|
| BLAKE2b-256 | 3a1655478916b2c5fce9bd0ce2182ebba044acf06f8399ab0f40e17d00ec335c |
