# Autogen Create Resource

> Use when creating a brand-new autogenerated (serviceapi) resource in this provider from an OpenAPI spec — "autogenerate new terraform resource <name>", a new-resource workflow dispatch, or any request to add a new autogen resource together with its acceptance tests, examples, docs, and changelog.

- Skill: `mongodb/autogen-create-resource` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mongodb/autogen-create-resource`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mongodb/autogen-create-resource/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mongodb (https://skillmd.com/u/mongodb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mongodb/autogen-create-resource

---


# Create a new autogen resource

Orchestrates the full new-resource flow: generated code plus the complementary artifacts. This skill owns sequencing and commands only — schema and config judgment lives in `autogen-config`, test conventions in `acceptance-test-patterns`, docs, examples, and changelog conventions in `pr-and-documentation-standards`.

## Inputs

1. **Resource name** — the future `tools/codegen/config.yml` key (strip any `mongodbatlas_` prefix; no `_api` suffix, that tier is internal-only).
2. **Spec source** — default is the prod spec. Otherwise the caller supplies a URL or an already-fetched local file passed as `spec_source`.
3. **Artifact selection** — which complementary artifacts to produce (a dispatch may deselect e.g. acceptance tests). Default: all.
4. **Output file** (optional) — `output_file`, the path the run summary is written to. Non-interactive callers such as a CI workflow supply it; when it is absent the summary is presented in the session instead.

## Flow

1. **Fetch and flatten the spec**
   ```bash
   make autogen-update-api-spec              # prod
   make autogen-update-api-spec spec_source=<url-or-file>
   ```
2. **Author the config.yml entry** — follow the `autogen-config` skill (path-to-CRUD mapping, version_header, aliases, ignores, wait, overrides).
3. **Generate**
   ```bash
   make autogen-generate-resources resource_name=<name>
   ```
4. **Schema review** — the post-generation review in `autogen-config`. Apply override fixes and regenerate before building artifacts on top of a wrong schema.
5. **Register in the provider** — manual edit to `internal/provider/provider.go`: add the `internal/serviceapi/<package>` import, then register only the surfaces codegen actually emitted. `Resource` exists only when the entry has resource CRUD operations, `DataSource` only with `datasources.read`, and `PluralDataSource` only with `datasources.list`, so check which files the generator produced (`resource.go`, `data_source.go`, `plural_data_source.go`) before adding entries: referencing a symbol codegen did not emit fails `go build`. `metricintegration` has all three; `aimodelorgapikey` is data-source-only. If the package name collides with a handwritten service, use an aliased import (see `autogenprojectipaccesslist`). Do **not** use `make enable-internal-autogen` — it registers every unregistered serviceapi package, including internal `_api` ones.
6. **Build**: `go build ./...`
7. **Complementary artifacts** (honoring the artifact selection):
   - **Acceptance tests** — `internal/serviceapi/<package>/resource_test.go` + `main_test.go`, following `acceptance-test-patterns` (consolidated resource+data-source test, optional-attribute lifecycle, checkExists/checkDestroy via the SDK's untyped client with the package's `apiVersionHeader` const). If the Go SDK lacks the endpoint, add a raw-HTTP helper under `internal/testutil/acc/` (see `metric_integration.go` there).
   - **CI wiring** — in `.github/workflows/acceptance-tests-runner.yml`: add `internal/serviceapi/<package>/*.go` to the `autogen_fast` change-detection filter group (`autogen_slow` only for long-provisioning resources), and add the package to `ACCTEST_PACKAGES`. Without this a new package belongs to no group and its tests never run on PRs. If the tests need external credentials, do not invent secret names — flag the secrets wiring (runner `secrets:` inputs, job env, `acceptance-tests.yml` pass-through) under "Needs human attention".
   - **Examples** — follow `pr-and-documentation-standards`. One flow: flat `examples/mongodbatlas_<name>/` with `main.tf`. Two or more flows: parent README plus use-case sibling directories (canonical: `examples/mongodbatlas_cloud_backup_collection_restore_job/`). Embed registry docs with `tffile`; do not paste HCL into `.md.tmpl`. Prerequisite third-party resources are defined inline or as input variables with best-effort realistic values, flagged for the author.
   - **Docs** — author a template per surface that exists: `templates/resources/<name>.md.tmpl`, and `templates/data-sources/<name>.md.tmpl` / `<name>s.md.tmpl` for the singular and plural data sources codegen emitted (subcategory, import section, any behavioral notes codegen can't produce), then `make generate-doc resource_name=<name>`.
   - **Changelog** — `.changelog/<PR number>.txt`: one `release-note:new-resource` block plus one `release-note:new-datasource` block per data source. Predict the number from the latest issue/PR number when reachable, otherwise from the highest existing `.changelog/` entry, and flag it for verification once the PR exists.
8. **Run summary** — see below.

## Structured run summary

End every run by producing a summary with two sections. Write it to `output_file` when the caller supplied one; otherwise present it in the session.

- **Reasoning** — the notable judgment calls: override choices and their upstream spec reports, aliases/ignores/wait decisions, acceptance-test scenarios covered, artifacts skipped by deselection, anything you could not verify.
- **Needs human attention** — aggregated follow-ups: prerequisite resources to provision, secrets wiring, likely `resource_custom_hooks.go` work (flag, never attempt), possible breaking changes, upstream module impact. Omit empty categories; state "None identified" if the list is empty.

When the spec source is not prod, state DO NOT MERGE prominently at the top of the summary. Do not create the PR; the caller (CI workflow or engineer) owns that.

## Error handling

| Error | Cause and resolution |
|---|---|
| `npx` or flattener fails | Node.js not installed — check `node --version`. |
| model-gen: "resource not found" | Name doesn't match the config.yml key. |
| model-gen: override error | Overrides can hit the same attribute on multiple surfaces — read the error, it may be a surface you did not intend. |
| code-gen failure | Structural issue in `tools/codegen/models/<name>.yaml` — inspect the model. |
| `go build ./...` fails on provider.go imports | Registration step incomplete, or it registers a surface codegen did not emit; may also need `go mod tidy`. |