Contributing

Thanks for your interest in contributing! aws-vault is a tool for securely storing and brokering AWS credentials, so we take care with every change that lands. This document explains how to contribute effectively.

Contributions are welcome and encouraged! Whether you're fixing a typo, adding a new feature, or suggesting improvements, your help is appreciated. Please use issues to discuss changes before opening a PR.

Before you start

Please read the following first:

• AI_POLICY.md — if you intend to use any AI assistance (Claude, Copilot, Cursor, etc.) for your contribution. The short version: AI is welcome, but its use must be disclosed, code must be human-tested, and AI-generated PRs require an accepted issue first. Drive-by AI PRs will be closed.
• SECURITY.md — if you've found a security vulnerability. Do not file a public issue. Follow the disclosure process there.
• CODE_OF_CONDUCT.md — we expect respectful, constructive interactions.

How to contribute

Reporting bugs and requesting features

Open an issue. Useful bug reports usually include:

• aws-vault --version
• Operating system and version
• Backend in use (Keychain, Secret Service, Pass, file, 1Password, etc.)
• A minimal reproduction (commands run, redacted output, expected vs. actual behaviour)
• Anything in ~/.aws/config that's relevant — with account IDs, ARNs, and other identifiers redacted
• Please use conventional commits and subjects for easier classification.

Never paste real credentials, access keys, session tokens, MFA serials, or full account IDs into an issue. Redact them.

Discussing changes first

For anything beyond a typo, doc clarification, or obvious bug fix, please open an issue before opening a PR. This is especially important for:

• New features or flags
• Changes to backends, credential handling, or the local metadata server
• Refactors that touch the vault/, server/, or prompt/ packages
• Anything affecting the security boundary

This saves you wasted effort if the change isn't a fit, and it gives the maintainer a chance to weigh in on the approach.

Pull requests

When you're ready to send a PR:

1. Fork the repo and create a topic branch from main.
2. Keep the PR focused — one logical change per PR.
3. Write a clear description: what problem you're solving and how. For example:

   "Add --auto-logout flag" is fine as a title, but the description should say why — e.g. "Users repeatedly hit the existing SSO session when switching profiles; this flag makes login clear it first."

4. Use Conventional Commits for commit messages and the PR title. Examples:

   feat: add 1Password Service Accounts backend
   fix(server): handle EC2 metadata timeouts cleanly
   docs: clarify pass backend setup on Fedora
   chore(deps): bump aws-sdk-go-v2
   

5. Make sure CI is green. The repo runs go vet, golangci-lint, and the test suite on every PR.
6. If your change is user-visible, update the relevant section of README.md or USAGE.md in the same PR.

What we look for when reviewing

• Intent is clear. We can tell from the description what problem the change solves.
• It fits the project's direction. aws-vault is intentionally narrow: secure local credential storage and brokering temporary AWS credentials. Features outside that scope are unlikely to land.
• Security posture is preserved. Anything that changes how credentials are stored, passed to subprocesses, served over the metadata endpoint, or persisted to disk gets extra scrutiny. Expect questions; they're not personal.
• Tests cover the change. New behaviour needs new tests. Bug fixes should include a regression test where practical.
• Code quality. Readable, idiomatic Go that fits the existing style. Linters clean.
• Backwards compatibility. Breaking changes to CLI flags, config, or backend behaviour need a strong justification and should be flagged clearly in the PR description.

Development setup

Requirements

• Go (see go.mod for the minimum version)
• make
• golangci-lint — install via the official instructions or:

  go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
  

Build and test

The repo uses a Makefile; common targets:

make build      # build the binary
make test       # run the test suite
make lint       # run golangci-lint

Or directly with the Go toolchain:

go build .
go test ./...
golangci-lint run ./...

Platform-specific notes

aws-vault integrates deeply with OS-level keystores, so some code paths only run on specific platforms:

• macOS — Keychain integration. Release builds are code-signed; for local development you can generate a self-signed code-signing certificate and sign with codesign --sign <cert-name> ./aws-vault.
• Windows — Credential Manager integration.
• Linux — Secret Service (GNOME Keyring / KWallet), Pass, Passage, or the encrypted file backend.

Please only submit changes to backends you can actually test on the relevant platform. Untested code for platforms you don't have access to is one of the failure modes called out in AI_POLICY.md and applies to manual contributions too.

What to expect from maintainers

aws-vault is maintained on a best-effort basis by volunteers. We aim to respond within a couple of weeks but cannot guarantee a timeline. If your PR has been quiet for more than two weeks, a polite ping is fine.

Maintainers may request changes, suggest a different approach, or occasionally decline a contribution. None of that is a comment on you — it's part of keeping a small, security-sensitive tool coherent over time.

Licensing

aws-vault is licensed under the MIT License. By submitting a contribution, you agree that your work will be made available under the same license.

---

Thanks for helping keep aws-vault healthy. 🔐