Skip to content

docs: contributing and readme update #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KT-Doan merged 3 commits into from
Mar 3, 2026
Merged

docs: contributing and readme update #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
964a56d
Adding documentation update
KT-Doan Mar 3, 2026
23ef6a2
Merge branch 'main' into docs/update_docs
KT-Doan Mar 3, 2026
da16aef
Adding documentation update
KT-Doan Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions .githooks/pre-commit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ if [ -n "$(gofmt -l .)" ]; then
echo "Error: The following files are not formatted:"
gofmt -l .
echo ""
echo "Run 'make fmt' to fix formatting."
echo "Run 'make format' to fix formatting."
exit 1
fi

Expand All @@ -21,12 +21,17 @@ go vet ./...

# Lint
echo "Running golangci-lint..."
if command -v golangci-lint &> /dev/null; then
if [ -x ".bin/golangci-lint" ]; then
.bin/golangci-lint run
elif command -v golangci-lint &> /dev/null; then
golangci-lint run
elif [ -x "$(go env GOPATH)/bin/golangci-lint" ]; then
"$(go env GOPATH)/bin/golangci-lint" run
else
echo "Warning: golangci-lint not found, skipping. Install with: make tools"
GOPATH_BIN="$(go env GOPATH 2>/dev/null)/bin/golangci-lint"
if [ -n "$GOPATH_BIN" ] && [ -x "$GOPATH_BIN" ]; then
"$GOPATH_BIN" run
else
echo "Warning: golangci-lint not found, skipping. Install with: make deps"
fi
fi

# Build check
Expand Down
51 changes: 32 additions & 19 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Thank you for your interest in contributing to the Ory Terraform Provider!

### Prerequisites

- [Go](https://golang.org/doc/install) >= 1.21
- [Go](https://golang.org/doc/install) (see version in `go.mod`)
- [Terraform](https://www.terraform.io/downloads) >= 1.0
- An [Ory Network](https://console.ory.sh/) account for testing
- An [Ory Network](https://console.ory.sh/) account for acceptance testing

### Building

Expand All @@ -17,14 +17,16 @@ Thank you for your interest in contributing to the Ory Terraform Provider!
git clone https://github.com/ory/terraform-provider-ory.git
cd terraform-provider-ory

# Install development tools and set up git hooks
make tools
make hooks
# Install dependencies
make deps

# Set up pre-commit hooks
git config core.hooksPath .githooks

# Build
make build

# Install locally
# Install locally (to ~/.terraform.d/plugins/)
make install
```

Expand All @@ -42,8 +44,8 @@ The provider has two types of tests:
Unit tests can be run without any credentials:

```bash
make test # Run all unit tests
make test-short # Run unit tests in short mode
make test # Run all unit tests with coverage
make test-short # Run unit tests in short mode (CI runs these with coverage enabled)
```

### Acceptance Tests
Expand All @@ -58,20 +60,26 @@ Acceptance tests run against a **pre-created Ory project**. The project must be
cp .env.example .env
```

The `.env` file is gitignored and automatically loaded by `make` targets. At minimum you need:
The `.env` file is gitignored and automatically loaded by `make` targets.

**Required** (validated by `make env-check`):

```bash
# Workspace credentials
ORY_WORKSPACE_API_KEY=ory_wak_...
ORY_WORKSPACE_ID=...
```

**Recommended** (needed by most resource tests):

# Pre-created test project
```bash
ORY_PROJECT_ID=...
ORY_PROJECT_SLUG=...
ORY_PROJECT_API_KEY=ory_pat_...
ORY_PROJECT_ENVIRONMENT=prod
```

When set, tests use this persistent project instead of creating ephemeral ones. The project must have keto namespaces and dynamic client registration configured. See `.env.example` for the full list of variables.

#### Running Acceptance Tests

```bash
Expand All @@ -94,6 +102,8 @@ Some tests require specific Ory plan features. Enable them with environment vari
| `ORY_PROJECT_TESTS_ENABLED=true` | Run project creation/deletion tests |
| `ORY_EVENT_STREAM_TESTS_ENABLED=true` | Run event stream tests (requires Enterprise plan + AWS setup below) |

> **Note:** CI enables **all** feature flags, including `ORY_PROJECT_TESTS_ENABLED`, on pull requests. Locally, `make test-acc-all` enables all flags **except** `ORY_PROJECT_TESTS_ENABLED` by default (project creation/deletion tests are excluded because they are slow and potentially destructive). To run those locally, set `ORY_PROJECT_TESTS_ENABLED=true` explicitly.

#### Event Stream Tests

Event stream tests have additional requirements beyond a feature flag because they interact with real AWS infrastructure:
Expand Down Expand Up @@ -208,7 +218,7 @@ To use a locally built provider, create a `~/.terraformrc` file:
```hcl
provider_installation {
dev_overrides {
"ory/terraform-provider-ory" = "/path/to/terraform-provider-ory"
"ory/ory" = "/path/to/terraform-provider-ory"
}
direct {}
}
Expand Down Expand Up @@ -267,14 +277,14 @@ After editing templates, run `make format` to regenerate docs.

### Pre-Commit Checklist

Run these checks locally before committing. They mirror what CI runs on every push.
Run these checks locally before committing. They mirror what CI runs on every pull request.

#### Required

```bash
make build # Verify the provider compiles
make format # Format code, tidy modules, regenerate docs, fix lint issues
make test # Run unit tests (no API calls needed)
make test-short # Run unit tests in short mode (matches CI)
```

`make format` runs several tools in sequence:
Expand All @@ -287,7 +297,8 @@ make test # Run unit tests (no API calls needed)
#### Recommended

```bash
make sec # Run all security scans (govulncheck + gosec + gitleaks)
make sec # Run security scans (govulncheck + gosec + gitleaks)
make sec-trivy # Run trivy vulnerability scan (requires build first)
make licenses # Check dependency licenses
```

Expand All @@ -298,16 +309,18 @@ You can also run security scans individually:
| `make sec-vuln` | govulncheck | Known Go vulnerabilities |
| `make sec-gosec` | gosec | Go security patterns (injection, file traversal, etc.) |
| `make sec-gitleaks` | gitleaks | Hardcoded secrets and credentials |
| `make sec-trivy` | trivy | Vulnerability, secret, and misconfig scanning |
| `make sec-trivy` | trivy | Vulnerability, secret, and misconfig scanning (not included in `make sec`) |

> **Note:** `make sec-trivy` is **not** included in `make sec` — it must be run separately and requires a prior `make build`.

#### Quick Reference

```bash
# Minimum before committing:
make build && make format && make test
make build && make format && make test-short

# Full CI-equivalent check:
make build && make format && make test && make sec && make licenses
make build && make format && make test-short && make sec && make sec-trivy && make licenses
```

### Code Style
Expand All @@ -332,7 +345,7 @@ docs: add algorithm guidance to JWK docs
1. Fork the repository
2. Create a feature branch from `main`
3. Make your changes
4. Run checks: `make build && make format && make test`
4. Run checks: `make build && make format && make test-short`
5. Submit a pull request using the PR template

Please include:
Expand Down
26 changes: 14 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ A Terraform provider for managing [Ory Network](https://www.ory.sh/) resources u
## Requirements

- [Terraform](https://www.terraform.io/downloads) >= 1.0
- [Go](https://golang.org/doc/install) >= 1.21 (for building from source)
- [Go](https://golang.org/doc/install) (see version in `go.mod`; for building from source)
- An [Ory Network](https://console.ory.sh/) account

## Installation
Expand Down Expand Up @@ -302,22 +302,24 @@ Acceptance tests run against a **pre-created Ory project**. Copy `.env.example`
cp .env.example .env
```

At minimum you need:
The `.env` file is gitignored and automatically loaded by `make` targets.

**Required** (validated by `make env-check`):

```bash
# Workspace credentials
ORY_WORKSPACE_API_KEY=ory_wak_...
ORY_WORKSPACE_ID=...
```

**Recommended** (needed by most resource tests):

# Pre-created test project
```bash
ORY_PROJECT_ID=...
ORY_PROJECT_SLUG=...
ORY_PROJECT_API_KEY=ory_pat_...
ORY_PROJECT_ENVIRONMENT=prod
```

The `.env` file is gitignored and automatically loaded by `make` targets.

```bash
make test-acc # Standard acceptance tests
make test-acc-verbose # With debug logging
Expand Down Expand Up @@ -433,26 +435,26 @@ templates/

### Pre-Commit Checklist

Run these checks locally before committing. They mirror what CI runs on every push.
Run these checks locally before committing. They mirror what CI runs on every pull request.

```bash
# Minimum before committing:
make build && make format && make test
make build && make format && make test-short

# Full CI-equivalent check:
make build && make format && make test && make sec && make licenses
make build && make format && make test-short && make sec && make sec-trivy && make licenses
```

`make format` runs several tools in sequence: `go fmt`, `gofmt -s`, `terraform fmt`, `go mod tidy`, `tfplugindocs generate`, and `golangci-lint --fix`.

### Security Scanning

```bash
make sec # Run all security scans
make sec # Run security scans (govulncheck + gosec + gitleaks)
make sec-vuln # govulncheck — known Go vulnerabilities
make sec-gosec # gosec — Go security patterns
make sec-gitleaks # gitleaks — hardcoded secrets
make sec-trivy # trivy — vulnerability and misconfig scanning
make sec-trivy # trivy — vulnerability and misconfig scanning (not included in `make sec`)
```

## Contributing
Expand All @@ -461,7 +463,7 @@ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed g

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Run checks: `make build && make format && make test`
3. Run checks: `make build && make format && make test-short`
4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format
5. Open a Pull Request

Expand Down