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.post129.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf2b17b8428553d9b43cad3c478f3ae79da4d4861604dfc506bfc9a26cf39d45 |
|
MD5 | 9ffbd4091277ea97b2a1958ede8a7903 |
|
BLAKE2b-256 | 3c88e3a304fedc2a1b3cfebae1d6dc1ce28d0da46ef995b5a8dff5f314a4b965 |
Hashes for actions_includes-0.0.post129-py3.9.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | a494c69c2e171c31531be0bcce348a46a86707e70fa1960f2fdf0f8dee631ae5 |
|
MD5 | 72d3fcc26b6468373e3ef672b5c21265 |
|
BLAKE2b-256 | 9532ec209a7617e5c4e0dc334a58232580386538dc35777a6ead3e305d880445 |
Hashes for actions_includes-0.0.post129-py3.8.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5b6c5ab13c1716122fa7efba2c217a864cf87fbe6003ae8a8de5126189f7868a |
|
MD5 | 5fba4f2f21c08a7a2fdf4caa94fbc6d6 |
|
BLAKE2b-256 | ac27a37f62d3683c52cff96386443ce32326efec3256ec2203976c2e98cfb5e2 |
Hashes for actions_includes-0.0.post129-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7f6344a87cf61442e5817347d80a2ee0dff4721a62655d85a4e7fa6d776167ad |
|
MD5 | 637c2a54db5411997414369106db194d |
|
BLAKE2b-256 | c3ba9731fdb54db9ff9ecd3bca2370197358eb272a60e8741781b77dc008e863 |