Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (92 loc) · 4.74 KB

CONTRIBUTING.md

File metadata and controls

142 lines (92 loc) · 4.74 KB
Raw

Contributing ✅

Thank you for contributing! This document explains how to get started, how to run tests and CI locally, and how to configure a Personal Access Token (PAT) as GITHUB_TOKEN so you can run GitHub Actions workflows locally using act.

Quick start 🔧

  • Fork the repository and create a branch for your change.
  • Open a concise PR with a clear description of what you changed and why.
  • Add tests and docs for new features or bug fixes.
  • Run linters and tests locally before submitting the PR.

Git commit signing in the dev container

The dev container mounts your host ~/.gitconfig and ~/.ssh directly, so commit signing works without any extra setup — as long as your signing key path uses a tilde rather than an absolute path. Absolute paths (e.g. /Users/yourname/.ssh/id.github.pub) do not resolve inside the container where HOME=/root.

Check your current config:

git config --global user.signingkey

If the output is an absolute path, fix it:

git config --global user.signingkey "~/.ssh/id.github.pub"

Verify signing works end-to-end by making a test commit and checking the signature:

git commit --allow-empty -m "test signing"
git log --show-signature -1

Run GitHub Actions locally with act 💡

We provide GitHub Actions workflows for CI. The devcontainer includes act and other tooling; the only manual step is to provide a GITHUB_TOKEN (this is a Personal Access Token, PAT) so workflows that rely on GITHUB_TOKEN will run locally.

Important: The PAT you create should be scoped to this repository only and you are responsible for creating, storing, rotating, and ultimately revoking this token. Never commit tokens to the repository.

1) Create a Scoped Personal Access Token (PAT) 🔐

  • Go to GitHub → Settings → Developer settings → Personal access tokens.
  • Prefer Fine-grained token (recommended) so you can limit access to this repository only.
  • When creating the token, select repository access to Only select repositories and choose this repository.
  • Grant the minimum permissions required to run workflows. Typical permissions:
    • Actions: Read & write (so workflows can run and update statuses)
    • Contents: Read & write (if workflows need to checkout or push changes)

If you must use a classic token, grant the repo (and workflow) scopes and restrict usage to the repo where possible.

2) Make the token available to act 🧪

You can provide GITHUB_TOKEN to act in several secure ways. Example options:

  • Temporarily in your shell (recommended for quick runs):

    export GITHUB_TOKEN=ghp_xxx-your-token-here
act -P <platform> -j <job-name>

  • Pass it on the act command line:

    act -s GITHUB_TOKEN=${GITHUB_TOKEN}

3) Create .secrets and .vars files

Workflows use GitHub secrets and repository variables that must be supplied locally. Both files are git-ignored, never commit them.

Create .secrets in the repo root with the secrets required by the workflow you want to run:

GITHUB_TOKEN=ghp_xxx-your-token-here
SOPS_AGE_KEY=AGE-SECRET-KEY-1...
OCI_REGISTRY_HARBOR_LOGIN=robot$...
OCI_REGISTRY_HARBOR_SECRET=...
KUBECONFIG=...

Create .vars in the repo root with the repository variables:

OCI_REGISTRY=harbor.peinser.com

act is configured (via .actrc) to load both files automatically on every run.

4) Run workflows locally

nce GITHUB_TOKEN is available in your environment, run act as you normally would. Use the Makefile targets. No need to pass flags manually:

# Run all workflows
make act

# Run a specific job
make act-job JOB=deploy-production

Security & responsibility ⚠️

  • You are responsible for creating, scoping, storing, and rotating your PAT.
  • Store the PAT securely (for example, in a reputable password manager such as 1Password, Bitwarden, or your organization's secret store); avoid storing tokens in plaintext files on disk.
  • Do not commit tokens or secret files to the repository.
  • Revoke the token when no longer required.

Contribution workflow (recommended) 🧭

  1. Create a topic branch from main (or the appropriate branch).
  2. Make small, focused commits with descriptive messages.
  3. Run tests and linters locally.
  4. Push your branch and open a Pull Request.
  5. Address review comments, re-run tests, and keep changes small.

Style & testing 📋

  • Follow the coding style of the project.
  • Add tests for bug fixes and new features.
  • Ensure CI passes before requesting a review.

Code of conduct ❤️

Respectful, constructive collaboration is expected. If you encounter issues, please follow the project's code of conduct.

Thank you for helping improve the project! 🎉