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
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
).
Project details
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
Hashes for actions-includes-0.0.post134.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5a82050e5c7bd0891024fa4f3758fe3801cfa25160d9e64762fc6014281a9e3d |
|
MD5 | a90e663c8c7d3579e3b4da1d90e5b417 |
|
BLAKE2b-256 | ec62626526548afce912c417749310678a9ee6aac4a724400784d48c4a34435e |
Hashes for actions_includes-0.0.post134-py3.9.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8b151eea592be32a664d539b3cad384bdee62b9186c31bb1dfaad4ab820d7e71 |
|
MD5 | c2c0b144961b871916455f18ac0b6b50 |
|
BLAKE2b-256 | 813e00e5f942f9d225449eb41f44adfab85b78b92a67201ab467b47581cbe5c5 |
Hashes for actions_includes-0.0.post134-py3.8.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | e38c6cb4262afa709fad85d81bdabe204315790ceaf21bdb64a47cf5aace23fe |
|
MD5 | 0313e4eb7c3cb16ad1f3580a4a9c4456 |
|
BLAKE2b-256 | 288630a26f2fc4796c33594fc7bec4b54f6c6d0570b8650c89c7172703b80f20 |
Hashes for actions_includes-0.0.post134-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 116db23b648f56e4af8150b07fb1c7a1df63463413e0c21c51357f24f61e1068 |
|
MD5 | fc7218d5f7b0a94af146aec0458c4038 |
|
BLAKE2b-256 | e7debd9d2e6eec058ff8f3973dbef9b6f1ed93d6158fba3cc6c149d18931d1af |