Skip to content

Contributing

This guide explains how to report issues, propose changes, and submit pull requests for the reusable workflows in this library.

Security Review

All changes that introduce or update a third-party action, change permissions, or affect the security posture of the library must be reviewed against the controls documented in docs/security/.

When the security docs apply

Change type Required review
New third-party action Full action selection criteria evaluation; document in issue or PR
Updated SHA pin Confirm the new SHA is reachable from a signed release tag
Permission change Verify against Permissions reference; justify any increase
Vulnerability fix Follow the mitigation steps and VEX process
Any other change Check the PR checklist for the two new security items

Quarterly ENISA alignment review

Once per quarter, a maintainer should open an Update Workflow issue with type Security improvement to:

  1. Check the EUVD and OSV.dev for new advisories affecting actions used in this library.
  2. Verify all open Dependabot alerts have been reviewed and are within the response time thresholds in Vulnerability Management.
  3. Update the compliance matrix if any control status has changed.
  4. Review and triage any security-labelled open issues.

Reporting Issues

Use the structured issue templates to open requests. GitHub will show you the template chooser when you click New issue in the repository.

Template When to use
Bug Report A workflow behaves incorrectly or fails unexpectedly
New Workflow You want to add a new reusable workflow to the library
Update Workflow A workflow needs a new input, a tool version bump, or a behavior change
EOL / Deprecate A workflow should be deprecated or removed

Workflow Lifecycle

Adding a New Workflow

  1. Open a New Workflow issue to discuss the proposal before writing code.
  2. Create .github/workflows/<verb>-<subject>.yaml with on: workflow_call. Follow the <verb>-<subject> naming convention (e.g. test-go-modules).
  3. Add a documentation file:
    • Grouped workflows (ansible, container, python): docs/workflows/<category>/<name>.md
    • Standalone workflows: docs/workflows/<name>.md
  4. Register the new page in mkdocs.yml under nav:.
  5. Add the workflow to the permissions table in docs/security/permissions.md.
  6. Update AGENTS.md if the repository structure or conventions change.
  7. Submit a pull request — the PR template includes a full checklist.

Updating a Workflow

  1. Open an Update Workflow issue for non-trivial changes to discuss the approach first.
  2. Edit the workflow YAML under .github/workflows/.
  3. Keep the documentation in sync: inputs table, permissions table, and usage example.
  4. For breaking changes, include a migration path in the docs and add a BREAKING CHANGE: footer to the commit message to trigger a major version bump.

Deprecating or Removing a Workflow

  1. Open an EOL / Deprecate issue to announce intent and gather feedback from users.
  2. Add a deprecation notice to the workflow YAML (as a comment) and to the docs page.
  3. After the deprecation window (at least one minor release), remove the workflow file, its documentation page, its entry in mkdocs.yml, and its row in docs/security/permissions.md.

Pull Requests

All changes go through a pull request to main. The PR template prompts you through the required checklist:

  • Workflow YAML created or updated
  • Documentation created or updated
  • Permissions table in docs/security/permissions.md updated
  • mkdocs.yml nav updated (for new pages)
  • AGENTS.md updated (if conventions changed)
  • All caller examples include permissions: {} at the workflow level
  • All third-party actions pinned to a commit SHA with version tag comment (e.g. @abc1234 # v3)
  • New third-party actions reviewed against the action selection criteria

Releases are automated by go-semantic-release on every push to main. Use Conventional Commits in your commit messages:

Prefix Effect
feat: New workflow or new input → minor version bump
fix: Bug fix → patch bump
docs:, ci:, chore: No release on its own
BREAKING CHANGE: footer Major version bump

Downstream Projects

The issue templates and PR template in this repository are designed for managing this shared library. Downstream projects that adopt these workflows may benefit from applying similar templates in their own repositories to standardise how they manage CI/CD configuration changes.

Copy and adapt the files from .github/ISSUE_TEMPLATE/ and .github/PULL_REQUEST_TEMPLATE.md to your project, adjusting the workflow list to those you actually use.

Similarly, add a Dependabot configuration to keep workflow SHA pins up to date automatically:

.github/dependabot.yaml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"
    commit-message:
      prefix: "ci: "

See Getting Started for full setup instructions.