mirror of
https://github.com/oauth2-proxy/oauth2-proxy.git
synced 2026-09-30 19:51:22 +02:00
135 lines
4.3 KiB
Markdown
135 lines
4.3 KiB
Markdown
# Contributing
|
|
|
|
Thank you for contributing to OAuth2 Proxy. We track bugs, feature requests,
|
|
and other work in GitHub issues. Please follow the issue and pull request
|
|
templates, including their checkboxes.
|
|
|
|
## Development setup
|
|
|
|
Fork the repository, clone your fork, create a feature branch, and download Go
|
|
dependencies:
|
|
|
|
```bash
|
|
git clone git@github.com:<YOUR_FORK>/oauth2-proxy.git
|
|
cd oauth2-proxy
|
|
git switch -c feature/<BRANCH_NAME>
|
|
go mod download
|
|
```
|
|
|
|
Install the Go version declared in the repository's `go.mod`. The
|
|
[Go installation guide](https://go.dev/doc/install) and
|
|
[Go downloads page](https://go.dev/dl/) explain how to install a specific
|
|
release.
|
|
|
|
We suggest [Visual Studio Code](https://code.visualstudio.com/docs/languages/go)
|
|
with the official
|
|
[Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go).
|
|
|
|
### Local testing and debugging
|
|
|
|
To run OAuth2 Proxy locally with an example upstream and identity provider,
|
|
use the Makefile in `contrib/local-environment`:
|
|
|
|
```bash
|
|
cd contrib/local-environment
|
|
make up
|
|
```
|
|
|
|
Other available environments include:
|
|
|
|
- Dex with alpha config: `make alpha-config-up`
|
|
- Keycloak: `make keycloak-up`
|
|
- Dex with nginx: `make nginx-up`
|
|
|
|
See that Makefile for the complete set of environments and their corresponding
|
|
tear-down commands. The default local credentials are usually
|
|
`admin@example.com` and `password`.
|
|
|
|
The environments use `localtest.me`:
|
|
|
|
- OAuth2 Proxy: <http://oauth2-proxy.localtest.me:4180>
|
|
- Upstream: <http://httpbin.localtest.me:8080>
|
|
- Dex: <http://dex.localtest.me:5556>
|
|
|
|
For VS Code debugging, create `.vscode/launch.json` from the "Run and Debug"
|
|
view and use `Go: Launch Package`. The following configurations start OAuth2
|
|
Proxy with the local Dex or Keycloak environments:
|
|
|
|
```jsonc
|
|
{
|
|
"version": "0.2.0",
|
|
"configurations": [
|
|
{
|
|
"name": "Launch OAuth2 Proxy with Dex",
|
|
"type": "go",
|
|
"request": "launch",
|
|
"mode": "auto",
|
|
"program": "${workspaceFolder}",
|
|
"args": [
|
|
"--config",
|
|
"contrib/local-environment/oauth2-proxy.cfg"
|
|
]
|
|
},
|
|
{
|
|
"name": "Launch OAuth2 Proxy with Keycloak",
|
|
"type": "go",
|
|
"request": "launch",
|
|
"mode": "auto",
|
|
"program": "${workspaceFolder}",
|
|
"args": [
|
|
"--config",
|
|
"contrib/local-environment/oauth2-proxy-keycloak.cfg"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Pull requests and issues
|
|
|
|
If you find a bug, open an issue. To fix a bug, create a feature branch, make
|
|
the change, and open a pull request against this repository. Mention the
|
|
related issue number in the pull request when applicable.
|
|
|
|
GitHub's required reviews and CODEOWNERS rules are the authoritative merge
|
|
approval process. Reviewers should use GitHub's native review interface to
|
|
approve changes.
|
|
|
|
### GitHub commands
|
|
|
|
Prow-style commands may be posted as their own line in issue and pull request
|
|
comments:
|
|
|
|
- `/assign` and `/unassign` assign or unassign users.
|
|
- `/area`, `/kind`, and `/provider` apply a configured classification label.
|
|
- `/help` adds the `help wanted` label.
|
|
|
|
On pull requests only, project reviewers may also use `/lgtm` and
|
|
`/lgtm cancel` to manage the review-readiness label.
|
|
Use the command rather than manually applying the label.
|
|
The label does not merge a pull request or replace GitHub approval requirements.
|
|
|
|
Issues and pull requests require a `kind/*` label. Use `/kind <value>` to add one.
|
|
|
|
## AI use
|
|
|
|
OAuth2 Proxy is built by humans for humans. Authentication and authorization
|
|
depend on trust between people and systems. That trust also matters in how we
|
|
work together.
|
|
|
|
You may use AI tools when contributing, but YOU must not replace human
|
|
communication or judgment using those tools. You must understand, test, and
|
|
review every AI-assisted change yourself. Write a clear, concise pull request
|
|
description and respond to review comments yourself.
|
|
|
|
Listing AI tooling as a co-author, co-signing commits using an AI tool, or
|
|
using the `assisted-by`, `co-developed` or similar commit trailer is not allowed.
|
|
|
|
The project maintainers will review contributions regardless of their origin.
|
|
But we may close issues or pull requests without comment when they appear to be
|
|
unreviewed automated output, low-quality slop, or contain essay-length descriptions
|
|
or comments that waste reviewer time.
|
|
|
|
If a contribution does not show the care needed for a high-quality change,
|
|
maintainers will not spend time reviewing it.
|