/gha

Some common GitHub actions and workflows

Primary LanguageTypeScriptMIT LicenseMIT

GitHub Actions and reusable workflows

The cmaster11/gha repository contains various GitHub Actions, reusable workflows, and a build system to version them all.

Actions

Workflows

Development (actions)

  1. Create a new action in the actions folder (e.g. action-test).
  2. Create PR and assign a release label (patch, minor, major).
    1. Note that versions start from 0, which means that, if you want to release a v1, you will need to use a major label in the PR.
  3. On PR merge, the action will be built and released to its own version branch (e.g. action-test/v1).
  4. You can then use the action in a GitHub Actions workflow with:
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - uses: cmaster11/gha@action-test/v1

Additional files

Any file stored in the action folder will be moved to the root of the repository in the release branch, which means that if the action folder contains a README.md file, it will become the main README of the repo.

Pure NodeJs actions

Create an index.ts file in the action folder and use the following configuration for the action.yml file:

runs:
  using: node20
  main: index.ts

Development (workflows)

  1. Create a new workflow in the .github/workflows folder, making sure its name starts either with wf- or workflow- ( e.g. wf-test or workflow-test).
  2. Create PR and assign a release label (patch, minor, major).
    1. Note that versions start from 0, which means that, if you want to release a v1, you will need to use a major label in the PR.
  3. On PR merge, the workflow will be released to its own version branch (e.g. wf-test/v1 or workflow-test/v1).
  4. You can then use the workflows in a GitHub Actions workflow with:
jobs:
  my-job:
    uses: cmaster11/gha/.github/workflows/wf-test.yml@wf-test/v1

Additional files

Assuming your workflow's name is wf-test.yml:

README

If a file such as wf-test.README.md is found, it will be moved to the root of the repository in the release branch and renamed to README.md, which means it will become the main README of the repo.

Sub-workflows

Any other workflows contained in the .github/workflows folder whose name starts with the main workflow's name and continues after a . will be also released together with the main workflow.

E.g., You could have another workflow such as wf-test.another.yml.

This makes it possible to have a main workflow that triggers any amount of dependent ones without having to worry about versioning.

You can then reuse these sub-workflows in your main one with:

jobs:
  parse:
    uses: ./.github/workflows/wf-test.another.yml

Build pipeline

%%
%% NOTE: the diagram is stored in `./ARCHITECTURE.mermaid`
%%

flowchart
    commit["Commit on a PR-branch"]

    subgraph wf-build.yml
        get-release-label["Job: get-release-label\nFind the release label\nassociated with the PR"]
        get-changed-dirs["Job: get-changed-dirs\nDetect changed actions\nand workflows"]
        test["Job: test\nRuns CI tests\n(Tests will fail if\nsome files still need\nto be generated)"]
        gen-test-catch-all-workflow["Job: gen-test-catch-all-workflow\nAutomatically generates\na workflow to run\nall test workflows"]
        subgraph build-phase
            build-actions["Job: build-actions\nBuilds all the changed actions"]
            build-workflows["Job: build-workflows\nBuilds all the changed workflows"]
        end
        cleanup["Job: cleanup\nIf the PR has been closed,\ndeletes all dev branches\ncreated during the PR's\nlifetime"]
        gen-test-catch-all-workflow --> build-phase
        test --> build-phase
        get-changed-dirs -- Generates the build matrix --> build-phase
        get-release-label --> build-phase
        post-build-test-actions["Job: post-build-test-actions\nTriggers testing jobs"]
        post-build-test-workflows["Job: post-build-test-workflows\nTriggers testing jobs"]
        build-actions -- " Releases the changed\nactions on their branches\n(dev or versioned) " --> post-build-test-actions
        build-workflows -- " Releases the changed\nworkflows on their branches\n(dev or versioned) " --> post-build-test-workflows
    end

    subgraph cmaster11-gha-ci-test-catch-all.yml
        ci-post-test["Job: ci-post-test\nNotifies GitHub about the result of the test"]

        subgraph test-action-example.yml
            test-action-example["Job: test\nTests the action"]
        end

        subgraph test-action-another.yml
            test-action-another["Job: test\nTests the action"]
        end

        subgraph test-wf-test.yml
            test-wf-test["Job: test\nTests the workflow"]
        end

        test-action-example --> ci-post-test
        test-action-another --> ci-post-test
        test-wf-test --> ci-post-test
    end

    post-build-test-actions --> test-action-example.yml
    post-build-test-actions --> test-action-another.yml
    post-build-test-workflows --> test-wf-test.yml

    gen-test-catch-all-workflow -- " Creates a new commit\ncontaining the generated\ntest catch-all workflow\nand re-triggers the\nwhole pipeline if\nfiles have changed " --> cmaster11-gha-ci-test-catch-all.yml
    commit --> wf-build.yml

Loading