Community health files and shared actions

Organisation-wide defaults and shared CI building blocks for the repositories of ELIXIR On-Cloud: the community health files that GitHub uses for every repository without its own version, the organisation's profile page, composite actions and workflow templates.

Community health files

GitHub uses these files for every repository of the organisation that doesn't have its own version (see GitHub's documentation on default community health files):

• code of conduct;
• contributing guidelines;
• governance document;
• security policy;
• support guide;
• issue templates;
• pull request template.

No overrides

No repository of the organisation may override these files, and there are no exceptions: the organisation's policies bind every repository, whoever maintains it. A repository that still has an override is being brought into line; until then, GitHub shows the repository's file instead of the organisation's. The policy covers the files above, not the discussion forms, which GitHub doesn't inherit.

• Why: GitHub uses a repository's own file instead of the default, in the root, in docs/ or in .github/, and in any letter case. One repository's CONTRIBUTING.md or SECURITY.md would therefore hide the organisation's rules from its contributors and reporters, and the rules would drift apart between repositories.
• General rules live here, in one place: change the defaults in this repository, by pull request.
• Repository specifics (development setup, local checks, language guidelines, the release process, the documentation build) live in each repository's documentation, at paths that GitHub doesn't match, for example docs/contributing/index.md (not docs/contributing.md), and are linked from the "Contributing" section of its README. They don't repeat the general rules; they link to them.
• Check a repository: in gh api repos/elixir-cloud-aai/<repo>/community/profile, the entries for the code of conduct, contributing guidelines, security policy, issue template and pull request template must point to this repository (ignore the others, such as the README and the license). The API doesn't list GOVERNANCE.md or SUPPORT.md, so also check that neither exists in the repository's root, .github/ or docs/.

profile/README.md is the organisation's home page on GitHub.

This repository is also the source of the organisation's discussion board: the forms in .github/DISCUSSION_TEMPLATE/ structure new posts in its Q&A and Adoption categories (one form per category, named after its slug).

Labels

All maintained repositories share one set of labels, in labels/labels.yml:

• labels: the labels every repository has, in the form <key>: <value> (type, type flag, priority, status, status flag, workload, flag). They match the organisation's default repository labels (organisation settings, Repository, Repository defaults), which GitHub gives to new repositories; keep both in line.
• temporary: labels that every repository has for a limited time, such as the ecp-wp4: milestones and deliverables, but that aren't defaults.
• repositories: the repositories that the sync script covers by default.

Change labels by pull request; once it is merged, a maintainer runs labels/sync.sh (with gh logged in as a user with write access, plus yq v4 and jq). It creates missing labels and aligns colours and descriptions; it never deletes labels, but reports labels a repository has beyond the file. --check only reports (exit status 1 on any difference, unlisted labels included); --all covers every repository of the organisation that isn't archived (read-only) or a fork:

labels/sync.sh --check   # report differences
labels/sync.sh           # fix them

Rename a label with gh label edit --name rather than deleting it, so that issues and pull requests keep it; GitHub's default labels (bug, enhancement, and so on) and labels that bots add (dependencies, python, and so on) aren't used: configure Dependabot with labels: ["type: dependencies"].

Shared actions

Composite actions, in actions/<name>/, that the other repositories share and pin to the commit of a release:

• gate: checks the results of the jobs a CI gate needs.
• pr-title: checks pull request titles.
• publish-release: creates the GitHub release of a tag with the curated notes followed by GitHub's generated notes, the organisation's release notes format.
• scan-image: scans Docker images with Trivy.

workflow-templates/ offers the PR title workflow as a template for new workflows in the organisation's repositories.

The maintainer releases the actions from signed version tags; RELEASING.md describes how they are versioned and released.

Development

CI (.github/workflows/ci.yml) runs the pre-commit hooks of .pre-commit-config.yaml: YAML syntax and GitHub's schemas (issue forms, workflows, actions, Dependabot), Markdown style (markdownlint), secrets (gitleaks), shell scripts (shellcheck) and the workflows (actionlint). Its test job runs the tests of the composite actions (tests/<action>/test.sh; those of publish-release use Python's unittest, as its script uses the standard library only), the actions themselves and the tests of the release scripts (tests/release/test.sh). Run them locally before you push:

pre-commit install
pre-commit run --all-files
# The whole checkout, as in CI (also untracked and ignored files)
pre-commit run --all-files --hook-stage manual gitleaks-all
bash tests/pr-title/test.sh
bash tests/gate/test.sh
bash tests/labels/test.sh
bash tests/publish-release/test.sh
bash tests/scan-image/test.sh
bash tests/release/test.sh

Contributing

Contributions are welcome! See the contributing guidelines and mind our code of conduct. Report vulnerabilities as described in our security policy. For help, see the support guide. How decisions are made is described in our governance document.