Tool for flattening include statements in GitHub actions workflow.yml files.
Project description
:warning: This project is mostly abandoned.
You are probably better using Composite Actions or Reusable workflows.
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
).
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.post140.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | ae286cc068da436b8eccd6dd1f8a1ec9849533fa14cdb54a87f5212adde9e023 |
|
MD5 | 58030b5350fb115391a4d58b9827dc7f |
|
BLAKE2b-256 | 619fba4db88e3de593eb1f324d4a0e4b37eca8c8f3144a2d649538c54d142fdd |
Hashes for actions_includes-0.0.post140-py3.9.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2836b72c81b88c75b3a3f3283ccd97c4b608ad6410a88e257202741beebe24fb |
|
MD5 | 9d288fffedb1d379f4cd988f129b889f |
|
BLAKE2b-256 | 409ea9edf71a0de9053cc369959d2008542d9e41e4e06975de9ceec01ba0a7f2 |
Hashes for actions_includes-0.0.post140-py3.8.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b3e0d8b897831ad862731b75e8f54308a73cdcef5ad696480fc9478831e2694 |
|
MD5 | cdfc90139889f9f436ff19ca5ff4da13 |
|
BLAKE2b-256 | 47d189cf20c281dbd29ed78a64b2717cc1d011eb060b39970dd7116c1ea09730 |
Hashes for actions_includes-0.0.post140-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3b2e06f524b3d89318894cee725eb3a0e272fbf24f0a1511f8a2455116a81ce6 |
|
MD5 | 99cc2c957758b3f6b853bc02a295a7ea |
|
BLAKE2b-256 | 7d47387a737967c37989c085fb9fc2830ceb5156e5585c6ff06f16889fd0a79a |