Reusable GitHub Workflows

This repository hosts Reusable GitHub Workflows.

The repository includes:

• add-to-project workflow: when a new issue or PR is added to a repository, it is also added - by default - to the SynchroGuard platform project or to the project defined by project-url input parameter with status new. When a new PR is added, the PR is assigned to its creator. When a PR is set to ready, reviewers from reviewers-team input parameter (default value backend-devs) or reviewers-individuals (comma separated) are added.
• manage-issues workflow: automated issue and PR management including stale issue detection and priority synchronization. The workflow includes two main jobs:
  • Stale Issue Management: Identifies issues older than stale-days (default: 60) without a current or future iteration and marks them as stale. Automatically removes the stale label if an issue is added to an iteration. Closes stale issues as "not planned" after close-after-days (default: 7) without updates or being added to an iteration. Supports skip-label (default: "keep") to exclude specific issues from stale processing - issues with this label are never marked stale or closed. Supports dry-run mode (default: false) for testing changes without applying them.
  • Priority Synchronization: Syncs priority values from GitHub Projects to issue labels (P0-P3) for security-labeled issues. Runs daily at midnight via schedule, can be triggered manually via workflow_dispatch with custom parameters, or called by other workflows.
• check-pr workflow: when a new PR is added to a repository or any change occurs to the PR, the PR is validated to be sure that labels are valid.
• clean-up-storage workflow: when a new PR is closed, related cache and artifact are deleted.
• deployment workflow: commit a container image tag in the k8s-deployments repository
• markdown workflow: lint all Markdown documents and checks that the links referenced in the documents are valid. If skip-spell-check: false, also, a spell checker is executed.
• release-notes workflow: automatically updates release notes using PR titles and labels.
• golang workflow: lint, test and benchmark Go Applications. The workflow includes authentication to GitHub Container Registry in case tests rely on private images. To retrieve the images, you need also to set read permission for the repository on the package. The workflow also scans for vulnerabilities.
• docker workflow: build and push Docker images and scans for vulnerabilities.
• clean-up-docker workflow: when a PR is closed, related docker images and untagged ones are deleted
• licensing workflow: add licensing information in file headers and check dependencies licensing compatibility.
• new-release workflow: create a new release (leveraging makefile to update packaging file version).

Some of these workflows are configured as starter workflows in the .github repository, so that you can add them at any time from the actions page.

How to add a shared workflow to this repository

1. The new workflow need to be callable, i.e., include:

   on:
     workflow_call:

   This type of trigger can also be used to specify input parameters, as discussed in Reusable GitHub Workflows documentation. In which case we recommend to also include default values.

2. Ideally, the workflow should be tested in this repository itself before being used in other repositories. In relation to this, it is then important that you trigger it with events such as issues or pull_request and that, for these events, that do not support input parameters, you find a way to pass default values. See markdown workflow for one of the possible way to solve the issue.

3. Once the new workflow is available in the main branch, you can call it using something like:

   jobs:
     add-to-project:
       uses: zaphiro-technologies/github-workflows/.github/workflows/add-to-project.yaml@main
       secrets: inherit

   Of course, you can also test it from a branch, in which case you can replace main with the branch name.

How to add a starter workflow to .github repository

Should you wish to advertise the re-usable workflow to your organization developers in the new action page:

1. You need to create a template in the .github repository in the folder workflow-templates:

   name: Project Management
   on:
     issues:
       types:
         - labeled
     pull_request:
       branches: [$default-branch]
       types:
         - labeled
     workflow_call:
   
   jobs:
     add-to-project:
       uses: zaphiro-technologies/github-workflows/.github/workflows/add-to-project.yaml@main
       secrets: inherit

2. You need to create a linked .properties.json file including the related metadata:

   {
     "name": "Zaphiro Project Management",
     "description": "Zaphiro Project Management starter workflow.",
     "iconName": "octicon project",
     "categories": ["Automation", "utilities"],
   }

   For icons, we leverage octicon icons.

You can find more information in starter workflows documentation.

Grammar check support

To support it in your repo, you need to download and install the grammar check script in your repository. You can customise parameters or just use what's in the script. In the GitHub action mode (the default mode), the script uses the set of parameters included in .gramma.json.

You can include files that you want to be ignored in the .grammarignore file.

To use the local mode, that uses additional rules, run:

./grammar-check.sh -m local

To check a single file using the interactive mode, run:

./grammar-check.sh -m local -f filename.md

To check a list of file using the interactive mode, run:

./grammar-check.sh -f "filename1.md filename2.md"

References

• Reusable GitHub Workflows
• octicon icons
• .github repository
• Starter workflows