Skip to content

Contributing to swarm-external-secrets

Thank you for your interest in contributing to swarm-external-secrets! 🎉 This project is a Docker Swarm secrets plugin that integrates with HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, OpenBao, and more. We welcome contributions of all kinds — bug fixes, new provider support, documentation improvements, and more.

Table of Contents

Code of Conduct

This project follows a standard open-source Code of Conduct. Please be respectful, inclusive, and constructive in all interactions. Harassment or abusive behaviour will not be tolerated.

Getting Started

Prerequisites

Make sure the following tools are installed on your system:

Tool Version Purpose
Go ≥ 1.24 Primary language
Docker latest Plugin build & testing
Makim latest Task runner
Lefthook latest Git hooks manager
golangci-lint latest Go linter
gosec latest Security scanner
goimports latest Import formatter
gocyclo latest Cyclomatic complexity checker

Install Go tools with:

go install golang.org/x/tools/cmd/goimports@latest
go install github.com/securego/gosec/v2/cmd/gosec@latest
go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

Fork & Clone

  1. Fork this repository on GitHub.
  2. Clone your fork locally:
git clone https://github.com/<your-username>/swarm-external-secrets.git
cd swarm-external-secrets
  1. Add the upstream remote:
git remote add upstream https://github.com/sugar-org/swarm-external-secrets.git

Set Up the Development Environment

Install Git hooks via the setup script (this configures Lefthook):

./setup-hooks.sh

Install Go module dependencies:

go mod download

Project Structure

swarm-external-secrets/
├── main.go            # Plugin entry point
├── driver.go          # Core Docker secrets driver logic
├── utils.go           # Shared utility functions
├── providers/         # Secret provider implementations
│   ├── vault/         # HashiCorp Vault / OpenBao
│   ├── aws/           # AWS Secrets Manager
│   └── azure/         # Azure Key Vault
├── monitoring/        # Health & metrics dashboard
├── scripts/           # Shell scripts for build, test, deploy
├── docs/              # Documentation sources
├── .makim.yaml        # Makim task definitions
├── lefthook.yml       # Git hook definitions
├── Dockerfile         # Plugin Docker image
└── docker-compose.yml # Local development stack

Development Workflow

Available Tasks (Makim)

This project uses Makim as a task runner. Common tasks are defined in .makim.yaml:

Task Command Description
Build makim scripts.build Build the plugin image
Test makim scripts.test Run all tests
Run makim scripts.run Start the plugin locally
Deploy makim scripts.deploy Deploy to target environment
Cleanup makim scripts.cleanup Remove containers & build artifacts
Health check makim scripts.check_plugin_service Check plugin service health
Demo rotation makim scripts.demo_rotation Run a secret rotation demo
Lint makim scripts.linter Run all linting tools
Full CI makim ci.all Run the same steps as CI (build → test → health check → cleanup)

Pre-commit Hooks (Lefthook)

Lefthook automatically runs the following checks before each commit:

Hook What it does
go-tidy Runs go mod tidy and stages go.mod/go.sum
go-fmt Formats staged .go files
go-vet Runs go vet ./...
go-imports Fixes import ordering with goimports
golangci-lint Full lint suite with a 10-minute timeout
gosec Security scan of all Go code
gocyclo Fails if cyclomatic complexity exceeds 17
eof-newline Ensures all staged text files end with a POSIX newline

Tip: To skip hooks in an emergency, use git commit --no-verify. Please do not make this a habit.

Building the Plugin

makim scripts.build
# or directly:
./scripts/build.sh

Running Tests

makim scripts.test
# or directly:
./scripts/test.sh

Linting

makim scripts.linter
# or run golangci-lint directly:
golangci-lint run ./... --timeout 10m

Submitting a Pull Request

  1. Keep main up to date:
git fetch upstream
git rebase upstream/main
  1. Create a feature branch with a descriptive name:
git checkout -b feat/add-gcp-provider
# or
git checkout -b fix/vault-rotation-timeout

  1. Write your code following the existing code style.

  2. Ensure all checks pass locally:

makim ci.all
  1. Commit your changes. Write clear, concise commit messages in the imperative mood:
  2. ✅ feat: add GCP Secret Manager provider
  3. ✅ fix: handle Vault token renewal race condition

  4. ❌ fixed stuff

  5. Push your branch and open a Pull Request against main.

  6. Fill in the PR template completely — include a description of the change, how it was tested, and any relevant issue numbers.

  7. A maintainer will review your PR. Address feedback promptly.

Adding a New Provider

To add support for a new secret backend:

  1. Create a new package under providers/<provider-name>/.
  2. Implement the provider interface expected by driver.go.
  3. Register the provider in driver.go with the appropriate SECRETS_PROVIDER value.
  4. Add configuration documentation to docs/MULTI_PROVIDER.md.
  5. Add integration tests in scripts/test.sh or a dedicated test script.
  6. Update the provider table in readme.md.

Documentation

Documentation lives in the docs/ directory and is built with MkDocs Material.

To preview the docs locally:

pip install mkdocs-material
mkdocs serve

When contributing documentation: - Keep language clear and concise. - Include working code snippets where possible. - Update the relevant guide (MULTI_PROVIDER.md, MONITORING.md, ROTATION.md, etc.) when changing behaviour.

Google Summer of Code 2026

swarm-external-secrets is participating in Google Summer of Code 2026 under OpenScienceLabs.

If you are a student looking to apply, please review the Project Ideas Wiki and start contributing early. Please focus on small implementations or bugfixes and only change the necessary code,"less is more." PRs that are too long or contain unnecessary changes are impossible to review and will be closed.

Feel free to ping us if you need help or use the #gsoc channel on discord.

Restrictions on Generative AI Usage

GSoC is a program centered on mentorship, learning, and authentic engagement with the open-source community. To maintain the integrity of the program and respect the time of our mentors, we have established the following guidelines regarding the use of Generative AI (LLMs like ChatGPT, Claude, GitHub Copilot, etc.):

  • Authentic Contribution: We expect all contributions , from proposal writing to final code to be the result of your own learning and critical thinking. While AI can be a supportive tool for debugging or boilerplate, it must not be the "author" of your work.
  • Zero-Value Submissions: Simply feeding a prompt to an AI and posting the output (whether as a code change, documentation update, or issue comment) is considered low-value and will be rejected. Contributions must include value added through your own technical competency and understanding of the project context.
  • Human-in-the-Loop: If you use generative AI as an aid, you must fully understand every change you submit. You are expected to explain the rationale behind your technical decisions during code reviews. If you cannot explain why a specific approach was taken, the contribution will not be accepted.
  • Prohibition of Automated Agents: The use of automated AI agents, bots, or scripts to submit issues or pull requests is strictly forbidden. Any account found using such tools to interact with the repository may be blocked and reported to the GSoC program administrators.
  • Disclosure: If AI was used significantly to assist in a contribution (e.g., to refactor a complex function), please disclose this in your pull request description. Transparency helps mentors provide better guidance.
  • Reviewer Capacity: Our mentors have limited bandwidth. To protect their capacity for human-to-human mentorship, we reserve the right to rigorously reject contributions that appear to be high-volume, AI-generated, or lack human verification.

We also prefer new contributors to follow these - Matplotlib : Restrictions on Generative AI Usage - Scipy : A policy on generative AI assisted contributions - kubernetes/steering : Guidance on Generative AI usage in Kubernetes Github Orgs

Getting Help

  • GitHub Issues – for bug reports and feature requests.
  • GitHub Discussions – for questions, ideas, and general conversation.
  • Wiki – for project ideas and longer-form documentation.

We appreciate every contribution, no matter how small. Thank you for helping make swarm-external-secrets better! 🚀