Skip to content

Commit 1b78316

Browse files
Richa JainHarness
Richa Jain
authored and
Harness
committed
[fix]: [DBOPS-2092]: Make repo agent friendly (#1360)
* e9f5fd fix: [DBOPS-2092]: Make repo agent friendly
1 parent f2057c7 commit 1b78316

File tree

10 files changed

+530
-0
lines changed

10 files changed

+530
-0
lines changed

‎AGENTS.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# AGENTS.md
2+
3+
## Project Overview
4+
5+
Terraform provider for Harness that enables infrastructure-as-code management of Harness CD and NextGen platform resources. This provider allows automation of applications, pipelines, environments, services, connectors, feature flags, GitOps configurations, and AutoStopping rules.
6+
7+
## Build System
8+
9+
- **Language**: Go 1.24
10+
- **Build tool**: Make
11+
- **Build command**: `make build`
12+
- **Install locally**: `make install`
13+
- **Clean**: `make clean`
14+
15+
## Testing
16+
17+
- **Run all unit tests**: `make test`
18+
- **Run acceptance tests**: `make testacc` (requires HARNESS_* environment variables)
19+
- **Run tests with coverage**: `make test-coverage`
20+
- **Run single test file**: `go test -v ./internal/service/platform/connector/... -run TestAccResourceConnector`
21+
- **Run single test case**: `go test -v ./path/to/package -run TestFunctionName`
22+
23+
### Acceptance Tests
24+
25+
Acceptance tests create real resources in Harness. Required environment variables:
26+
- `HARNESS_ACCOUNT_ID`
27+
- `HARNESS_API_KEY`
28+
- `HARNESS_PLATFORM_API_KEY`
29+
30+
## Linting & Formatting
31+
32+
- **Format code**: `make fmt`
33+
- **Check formatting**: `make fmt-check`
34+
- **Run vet**: `make vet`
35+
- **Run linter**: `make lint` (uses golangci-lint)
36+
- **Run all checks**: `make check` (fmt-check + vet)
37+
38+
## Git Workflow
39+
40+
- **Commit format**: `type: [JIRA-TICKET]: Description`
41+
- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`
42+
- Jira prefixes: DBOPS, CDS, CCM, IAC, PL, AH, and others
43+
- Example: `feat: [DBOPS-2019]: Add usePercona field support in schema resource`
44+
- **Default branch**: `main`
45+
46+
## DOs
47+
48+
- Always run `make check` before committing to verify formatting and static analysis
49+
- Add changelog entries in `.changelog/` for user-facing changes (see README for format)
50+
- Run `make test` to ensure unit tests pass before pushing
51+
- Follow existing code patterns in the codebase
52+
- Use descriptive commit messages with Jira ticket references
53+
- Run `make docs` after modifying resource schemas to regenerate documentation
54+
- Use `make dev-setup` when setting up the development environment for the first time
55+
56+
## DON'Ts
57+
58+
- Never force push to main/master
59+
- Never commit secrets, .env files, or credentials
60+
- Never run `make sweep` without explicit confirmation - it destroys test resources and can be dangerous if misconfigured
61+
- Never skip code quality checks before committing
62+
- Never modify generated documentation files in `docs/` directly - regenerate with `make docs`
63+
64+
## Commands to Never Run
65+
66+
- `git push --force origin main`
67+
- `git push --force origin master`
68+
- `git commit --no-verify` or `git push --no-verify`
69+
- `make sweep` (without explicit user confirmation)
70+
- `rm -rf /` or any destructive recursive deletes
71+
72+
## Project Structure
73+
74+
```
75+
terraform-provider-harness/
76+
├── main.go # Provider entry point
77+
├── Makefile # Build, test, and development commands
78+
├── go.mod # Go module definition
79+
├── internal/ # Internal packages (not importable externally)
80+
│ ├── provider/ # Terraform provider configuration
81+
│ ├── service/ # Resource implementations by service
82+
│ │ ├── cd/ # First Generation CD resources
83+
│ │ ├── cd_nextgen/ # NextGen CD resources
84+
│ │ ├── chaos/ # Chaos Engineering resources
85+
│ │ ├── pipeline/ # Pipeline resources
86+
│ │ ├── platform/ # Platform resources (connectors, secrets, etc.)
87+
│ │ └── service_discovery/ # Service discovery resources
88+
│ ├── acctest/ # Acceptance test utilities
89+
│ ├── sweep/ # Resource sweepers for test cleanup
90+
│ ├── test/ # Test utilities
91+
│ └── utils/ # Utility functions
92+
├── docs/ # Generated Terraform documentation
93+
├── examples/ # Example Terraform configurations
94+
├── templates/ # Documentation templates
95+
├── scripts/ # Build and utility scripts
96+
├── helpers/ # Helper utilities
97+
└── .changelog/ # Changelog entries for releases
98+
```
99+
100+
## Important Packages
101+
102+
These are the most actively developed areas based on recent commit history:
103+
104+
- `internal/service/platform/` - Platform resources (connectors, secrets, users, etc.)
105+
- `internal/service/cd_nextgen/` - NextGen CD resources (environments, services, infrastructure)
106+
- `internal/service/pipeline/` - Pipeline resources
107+
- `internal/acctest/` - Acceptance test utilities
108+
109+
## Resource Development Guidelines
110+
111+
When creating or modifying Terraform resources:
112+
113+
1. **Schema Definition**: Define resource schema in the resource file with clear descriptions
114+
2. **CRUD Operations**: Implement Create, Read, Update, Delete functions
115+
3. **Testing**: Write both unit tests and acceptance tests
116+
4. **Documentation**: Schema descriptions auto-generate docs via `make docs`
117+
5. **Changelog**: Add entry in `.changelog/<PR_NUMBER>.txt`
118+
119+
## Dependencies
120+
121+
Key dependencies (from go.mod):
122+
- `github.com/harness/harness-go-sdk` - Harness Go SDK
123+
- `github.com/harness/harness-openapi-go-client` - Harness OpenAPI client
124+
- `github.com/hashicorp/terraform-plugin-sdk/v2` - Terraform Plugin SDK
125+
- `github.com/stretchr/testify` - Testing utilities
126+
127+
## Language-Specific Guidelines
128+
129+
This is a Go codebase. Follow Go conventions:
130+
- Use `gofmt` for formatting (handled by `make fmt`)
131+
- Follow effective Go guidelines
132+
- Use meaningful variable and function names
133+
- Handle errors explicitly
134+
- Write table-driven tests where appropriate

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎docs/AGENTS.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# AGENTS.md - Documentation
2+
3+
## Purpose
4+
5+
This directory contains auto-generated Terraform provider documentation. The documentation is generated from resource and data source schema descriptions using `tfplugindocs`.
6+
7+
## Directory Structure
8+
9+
```
10+
docs/
11+
├── index.md # Provider overview and configuration
12+
├── guides/ # User guides and tutorials
13+
├── resources/ # Resource documentation (auto-generated)
14+
│ ├── platform_connector_*.md
15+
│ ├── platform_organization.md
16+
│ ├── platform_project.md
17+
│ └── ...
18+
└── data-sources/ # Data source documentation (auto-generated)
19+
├── platform_connector_*.md
20+
└── ...
21+
```
22+
23+
## Regenerating Documentation
24+
25+
Run from the repository root:
26+
```sh
27+
make docs
28+
```
29+
30+
This executes `scripts/generate-docs.sh` which:
31+
1. Runs `tfplugindocs generate`
32+
2. Preserves subcategory frontmatter in existing docs
33+
3. Formats the generated markdown
34+
35+
## Documentation Templates
36+
37+
Templates for documentation are in `templates/`:
38+
- Resource templates define the structure of resource docs
39+
- Data source templates define the structure of data source docs
40+
41+
## Frontmatter
42+
43+
Each documentation file has YAML frontmatter:
44+
```yaml
45+
---
46+
page_title: "harness_platform_connector_github Resource - terraform-provider-harness"
47+
subcategory: "Next Gen"
48+
description: |-
49+
Resource for creating a GitHub connector.
50+
---
51+
```
52+
53+
The `subcategory` field determines navigation grouping on the Terraform Registry.
54+
55+
## Schema Descriptions
56+
57+
Documentation is generated from schema descriptions in resource code:
58+
```go
59+
Schema: map[string]*schema.Schema{
60+
"identifier": {
61+
Description: "Unique identifier of the resource.", // This becomes docs
62+
Type: schema.TypeString,
63+
Required: true,
64+
},
65+
}
66+
```
67+
68+
## Validation
69+
70+
Validate documentation:
71+
```sh
72+
make docs-validate
73+
```
74+
75+
## DOs
76+
77+
- Always regenerate docs after modifying resource schemas
78+
- Write clear, user-friendly descriptions in schema definitions
79+
- Use proper markdown formatting in descriptions
80+
- Keep frontmatter `subcategory` consistent
81+
82+
## DON'Ts
83+
84+
- Don't manually edit files in `docs/resources/` or `docs/data-sources/` - they will be overwritten
85+
- Don't commit docs changes without running `make docs` first
86+
- Don't remove frontmatter from generated files
87+
88+
## Updating index.md and guides/
89+
90+
The `docs/index.md` and files in `docs/guides/` are NOT auto-generated and can be manually edited. These provide:
91+
- Provider configuration examples
92+
- Authentication guidance
93+
- Usage tutorials

‎docs/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎internal/service/platform/connector/AGENTS.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# AGENTS.md - Connector Resources
2+
3+
## Purpose
4+
5+
This package implements Terraform resources and data sources for Harness connectors. Connectors provide integration with external systems like cloud providers, monitoring tools, ticketing systems, and secret managers.
6+
7+
## Package Structure
8+
9+
```
10+
connector/
11+
├── connector.go # Base functions shared by all connectors
12+
├── data_source_connector.go # Generic connector data source
13+
├── secret_ref_util.go # Secret reference utilities
14+
├── secretManagers/ # Secret manager connector implementations
15+
│ ├── aws_kms.go
16+
│ ├── aws_secrets_manager.go
17+
│ ├── azure_key_vault.go
18+
│ ├── gcp_kms.go
19+
│ ├── gcp_secret_manager.go
20+
│ ├── hashicorp_vault.go
21+
│ └── ...
22+
├── appdynamics.go # AppDynamics connector
23+
├── aws_cc.go # AWS Cloud Cost connector
24+
├── azure_cloud_cost.go # Azure Cloud Cost connector
25+
├── datadog.go # Datadog connector
26+
├── dynatrace.go # Dynatrace connector
27+
├── elasticsearch.go # Elasticsearch connector
28+
├── gcp_cloud_cost.go # GCP Cloud Cost connector
29+
├── jdbc.go # JDBC database connector
30+
├── jira.go # Jira connector
31+
├── kubernetes_cloud_cost.go # Kubernetes Cloud Cost connector
32+
├── newrelic.go # New Relic connector
33+
├── pagerduty.go # PagerDuty connector
34+
├── prometheus.go # Prometheus connector
35+
├── service_now.go # ServiceNow connector
36+
├── splunk.go # Splunk connector
37+
├── sumologic.go # Sumo Logic connector
38+
└── *_test.go # Test files for each connector
39+
```
40+
41+
## Base Functions (connector.go)
42+
43+
All connector resources should use these base functions:
44+
45+
```go
46+
// For resource Read operations
47+
resourceConnectorReadBase(ctx, d, meta, connType)
48+
49+
// For data source Read operations
50+
dataConnectorReadBase(ctx, d, meta, connType)
51+
52+
// For Create/Update operations
53+
resourceConnectorCreateOrUpdateBase(ctx, d, meta, connector)
54+
55+
// For Delete operations
56+
resourceConnectorDelete(ctx, d, meta)
57+
```
58+
59+
## Creating a New Connector Resource
60+
61+
1. Create `<connector_type>.go` with:
62+
- `Resource<ConnectorType>()` function returning `*schema.Resource`
63+
- Schema definition using `helpers.MergeSchemas`
64+
- CRUD context functions that call base functions
65+
66+
2. Create `<connector_type>_data_source.go` for the data source
67+
68+
3. Create `<connector_type>_test.go` and `<connector_type>_data_source_test.go` for tests
69+
70+
4. Register in `internal/provider/provider.go`:
71+
- Add import alias (e.g., `pl_connector_newtype "github.com/harness/terraform-provider-harness/internal/service/platform/connector"`)
72+
- Add to `ResourcesMap` and `DataSourcesMap`
73+
74+
## Common Patterns
75+
76+
### Schema Definition
77+
```go
78+
func Resource<ConnectorType>() *schema.Resource {
79+
resource := &schema.Resource{
80+
Description: "Resource for creating a <Type> connector.",
81+
ReadContext: resource<ConnectorType>Read,
82+
CreateContext: resource<ConnectorType>CreateOrUpdate,
83+
UpdateContext: resource<ConnectorType>CreateOrUpdate,
84+
DeleteContext: resourceConnectorDelete, // Uses shared delete
85+
Importer: helpers.MultiLevelResourceImporter,
86+
Schema: helpers.MergeSchemas(
87+
commonConnectorSchema(), // Common fields
88+
connectorTypeSpecificSchema(), // Type-specific fields
89+
),
90+
}
91+
return resource
92+
}
93+
```
94+
95+
### Secret References
96+
Use `secret_ref_text` constant for secret reference fields:
97+
```go
98+
const secret_ref_text = "Reference to a secret for the key. To reference a secret at the organization scope, prefix 'org' to the expression: org.{identifier}. To reference a secret at the account scope, prefix 'account` to the expression: account.{identifier}."
99+
```
100+
101+
## Testing
102+
103+
Run tests for a specific connector:
104+
```sh
105+
go test -v ./internal/service/platform/connector/... -run TestAccResourceConnector<Type>
106+
```
107+
108+
Run all connector tests:
109+
```sh
110+
go test -v ./internal/service/platform/connector/... -timeout 120m
111+
```
112+
113+
## API Client
114+
115+
Uses the Platform client from the session:
116+
```go
117+
c, ctx := meta.(*internal.Session).GetPlatformClientWithContext(ctx)
118+
```
119+
120+
Connector API calls:
121+
- `c.ConnectorsApi.GetConnector()`
122+
- `c.ConnectorsApi.CreateConnector()`
123+
- `c.ConnectorsApi.UpdateConnector()`
124+
- `c.ConnectorsApi.DeleteConnector()`
125+
126+
## DOs
127+
128+
- Use base functions from `connector.go` for CRUD operations
129+
- Use `helpers.MergeSchemas` to combine common and specific schemas
130+
- Use `secret_ref_text` constant for secret reference field descriptions
131+
- Add both resource and data source implementations
132+
- Add comprehensive acceptance tests
133+
134+
## DON'Ts
135+
136+
- Don't duplicate common connector logic - use base functions
137+
- Don't hardcode account/org/project IDs - use schema values
138+
- Don't forget to register new connectors in provider.go
139+
- Don't add local .terraform or terraform.tfstate files to git

‎internal/service/platform/connector/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)