{"id":29536931,"url":"https://github.com/grafbase/terraform-provider-grafbase","last_synced_at":"2025-08-01T13:37:49.283Z","repository":{"id":302291993,"uuid":"1011418897","full_name":"grafbase/terraform-provider-grafbase","owner":"grafbase","description":"Grafbase Terraform Provider","archived":false,"fork":false,"pushed_at":"2025-07-10T14:39:44.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T21:12:35.962Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T19:36:54.000Z","updated_at":"2025-07-10T14:38:36.000Z","dependencies_parsed_at":"2025-07-01T15:53:58.862Z","dependency_job_id":null,"html_url":"https://github.com/grafbase/terraform-provider-grafbase","commit_stats":null,"previous_names":["grafbase/terraform-provider-grafbase"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/grafbase/terraform-provider-grafbase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafbase%2Fterraform-provider-grafbase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafbase%2Fterraform-provider-grafbase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafbase%2Fterraform-provider-grafbase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafbase%2Fterraform-provider-grafbase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafbase","download_url":"https://codeload.github.com/grafbase/terraform-provider-grafbase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafbase%2Fterraform-provider-grafbase/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265563210,"owners_count":23788666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-17T03:38:53.638Z","updated_at":"2025-07-17T03:38:54.594Z","avatar_url":"https://github.com/grafbase.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafbase Terraform Provider\n\nThis Terraform provider allows you to manage Grafbase resources using the Grafbase API.\n\n## Requirements\n\n- [Terraform](https://www.terraform.io/downloads.html) \u003e= 1.5\n- [Go](https://golang.org/doc/install) \u003e= 1.21 (for building from source)\n- Valid Grafbase API key\n\n## Quick Start\n\n### 1. Configure the Provider\n\nAdd the provider to your Terraform configuration:\n\n```hcl\nterraform {\n  required_providers {\n    grafbase = {\n      source = \"grafbase/grafbase\"\n    }\n  }\n}\n\nprovider \"grafbase\" {\n  # API key can be set via GRAFBASE_API_KEY environment variable\n  # or explicitly set here (not recommended for production)\n}\n```\n\n### 2. Set Your API Key\n\n```bash\nexport GRAFBASE_API_KEY=\"your-grafbase-api-key\"\n```\n\n### 3. Create a Graph\n\n```hcl\nresource \"grafbase_graph\" \"example\" {\n  account_slug = \"my-account\"\n  slug         = \"my-graph\"\n}\n\noutput \"graph_id\" {\n  value = grafbase_graph.example.id\n}\n```\n\n### 4. Apply the Configuration\n\n```bash\nterraform init\nterraform plan\nterraform apply\n```\n\n## Building The Provider\n\n### From Source\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/grafbase/terraform-provider-grafbase\n   cd terraform-provider-grafbase\n   ```\n\n2. Build the provider:\n   ```bash\n   go build -o terraform-provider-grafbase\n   ```\n\n3. (Optional) Install locally for development:\n   ```bash\n   make install\n   ```\n\n### Using the Development Script\n\nFor a complete development setup:\n\n```bash\n./scripts/dev-setup.sh\n```\n\nThis script will:\n- Check dependencies\n- Build the provider\n- Run tests\n- Install the provider locally\n- Create development configuration\n\n## Authentication\n\nThe provider supports multiple authentication methods:\n\n### Environment Variable (Recommended)\n\n```bash\nexport GRAFBASE_API_KEY=\"your-api-key-here\"\n```\n\n### Provider Configuration\n\n```hcl\nprovider \"grafbase\" {\n  api_key = var.grafbase_api_key\n}\n\nvariable \"grafbase_api_key\" {\n  description = \"Grafbase API key\"\n  type        = string\n  sensitive   = true\n}\n```\n\n### Getting Your API Key\n\n1. Visit the [Grafbase Dashboard](https://app.grafbase.com/)\n2. Navigate to your organization's settings page\n3. Generate a new access token\n4. Store it securely (e.g., in your environment or secret management system)\n\n## Resources\n\n### `grafbase_graph`\n\nThe `grafbase_graph` resource allows you to manage graphs. Graphs are the fundamental units in Grafbase that contain your GraphQL schema and configuration.\n\n#### Example Usage\n\n**Basic Usage:**\n```hcl\nresource \"grafbase_graph\" \"example\" {\n  account_slug = \"my-account\"\n  slug         = \"my-graph\"\n}\n```\n\n**With Variables:**\n```hcl\nvariable \"environment\" {\n  description = \"Environment name\"\n  type        = string\n  default     = \"dev\"\n}\n\nresource \"grafbase_graph\" \"app\" {\n  account_slug = \"my-account\"\n  slug         = \"my-app-${var.environment}\"\n}\n```\n\n#### Argument Reference\n\nThe following arguments are supported:\n\n- `account_slug` (Required, String) - The slug of the Grafbase account where the graph will be created. This must be an existing account that you have access to. Changing this attribute forces replacement of the resource.\n\n- `slug` (Required, String) - The slug for the graph. Must be unique within the specified account and follow Grafbase naming conventions (lowercase letters, numbers, and hyphens). Changing this attribute forces replacement of the resource.\n\n#### Attribute Reference\n\nIn addition to all arguments above, the following attributes are exported:\n\n- `id` (String) - The unique identifier of the graph assigned by Grafbase.\n- `created_at` (String) - The RFC3339 timestamp when the graph was created.\n\n#### Import\n\nExisting graphs can be imported using the format `account_slug/graph_slug`:\n\n```bash\n# Import a specific graph\nterraform import grafbase_graph.example my-account/my-graph\n\n# Import with resource name matching the graph slug\nterraform import grafbase_graph.my_graph my-account/my-graph\n```\n\n#### Notes\n\n- **Immutability**: Both `account_slug` and `slug` are immutable after creation. Changing either will destroy and recreate the graph.\n- **Uniqueness**: Graph slugs must be unique within an account.\n- **Naming**: Follow Grafbase naming conventions for slugs (lowercase, alphanumeric, hyphens allowed).\n- **Permissions**: You must have appropriate permissions in the specified account to create graphs.\n\n### `grafbase_branch`\n\nThe `grafbase_branch` resource allows you to manage branches within a graph. Branches enable you to have different environments and configurations for your GraphQL API.\n\n#### Example Usage\n\n**Basic Usage:**\n```hcl\nresource \"grafbase_graph\" \"example\" {\n  account_slug = \"my-account\"\n  slug         = \"my-graph\"\n}\n\nresource \"grafbase_branch\" \"main\" {\n  account_slug = grafbase_graph.example.account_slug\n  graph_slug   = grafbase_graph.example.slug\n  name         = \"main\"\n}\n```\n\n**Multiple Branches:**\n```hcl\nresource \"grafbase_graph\" \"app\" {\n  account_slug = \"my-account\"\n  slug         = \"my-app\"\n}\n\nresource \"grafbase_branch\" \"main\" {\n  account_slug = grafbase_graph.app.account_slug\n  graph_slug   = grafbase_graph.app.slug\n  name         = \"main\"\n}\n\nresource \"grafbase_branch\" \"staging\" {\n  account_slug = grafbase_graph.app.account_slug\n  graph_slug   = grafbase_graph.app.slug\n  name         = \"staging\"\n}\n\nresource \"grafbase_branch\" \"feature\" {\n  account_slug = grafbase_graph.app.account_slug\n  graph_slug   = grafbase_graph.app.slug\n  name         = \"feature-new-schema\"\n}\n```\n\n#### Argument Reference\n\nThe following arguments are supported:\n\n- `account_slug` (Required, String) - The slug of the Grafbase account where the branch's graph exists. Changing this attribute forces replacement of the resource.\n\n- `graph_slug` (Required, String) - The slug of the graph where this branch will be created. Changing this attribute forces replacement of the resource.\n\n- `name` (Required, String) - The name of the branch. Must be unique within the graph and follow Grafbase naming conventions. Changing this attribute forces replacement of the resource.\n\n#### Attribute Reference\n\nIn addition to all arguments above, the following attributes are exported:\n\n- `id` (String) - The unique identifier of the branch assigned by Grafbase.\n- `environment` (String) - The environment type of the branch (either `PREVIEW` or `PRODUCTION`).\n- `operation_checks_enabled` (Boolean) - Whether operation checks are enabled for this branch.\n- `operation_checks_ignore_usage_data` (Boolean) - Whether usage data should be ignored when running operation checks.\n\n#### Import\n\nExisting branches can be imported using the format `account_slug/graph_slug/branch_name`:\n\n```bash\n# Import a specific branch\nterraform import grafbase_branch.main my-account/my-graph/main\n\n# Import a feature branch\nterraform import grafbase_branch.feature my-account/my-graph/feature-auth\n```\n\n#### Notes\n\n- **Immutability**: All input attributes (`account_slug`, `graph_slug`, and `name`) are immutable after creation. Changing any of them will destroy and recreate the branch.\n- **Production Branch**: The production branch (typically named \"main\") cannot be deleted. Attempting to delete it will result in an error.\n- **Branch Names**: Branch names must be unique within a graph and follow Grafbase naming conventions.\n- **Dependencies**: The graph must exist before creating branches. Use Terraform dependencies to ensure proper ordering.\n\n## Examples\n\nExplore the `examples/` directory for complete usage examples:\n\n- [`examples/main.tf`](examples/main.tf) - Basic usage with variables\n- [`examples/complete/`](examples/complete/) - Advanced multi-graph setup\n- [`examples/dev-setup/`](examples/dev-setup/) - Local development configuration\n\n## Development\n\n### Prerequisites\n\n- Go 1.21 or later\n- Terraform 1.5 or later\n- Make (optional, for using Makefile commands)\n\n### Quick Development Setup\n\nUse the provided development script for a complete setup:\n\n```bash\n./scripts/dev-setup.sh\n```\n\nThis will handle all the setup steps automatically.\n\n### Manual Development Setup\n\n1. **Clone and build:**\n   ```bash\n   git clone https://github.com/grafbase/terraform-provider-grafbase\n   cd terraform-provider-grafbase\n   go mod download\n   make build\n   ```\n\n2. **Run tests:**\n   ```bash\n   make test\n   ```\n\n3. **Install locally:**\n   ```bash\n   make install\n   ```\n\n### Available Make Commands\n\n```bash\nmake build      # Build the provider binary\nmake test       # Run unit tests\nmake testacc    # Run acceptance tests (requires TF_ACC=1 and valid API key)\nmake install    # Install provider locally for development\nmake clean      # Clean build artifacts\nmake fmt        # Format Go code\nmake lint       # Run linter (requires golangci-lint)\nmake docs       # Generate documentation\nmake dev-setup  # Setup development environment\nmake debug      # Run provider in debug mode\n```\n\n### Testing\n\n#### Unit Tests\n```bash\ngo test ./...\n```\n\n#### Acceptance Tests\nAcceptance tests require a valid Grafbase API key and will create real resources:\n\n```bash\nexport GRAFBASE_API_KEY=\"your-api-key\"\nexport TF_VAR_account_slug=\"your-test-account\"\nTF_ACC=1 go test ./... -v\n```\n\n### Local Development with Terraform\n\n1. **Build the provider:**\n   ```bash\n   go build -o terraform-provider-grafbase\n   ```\n\n2. **Create a `.terraformrc` file:**\n   ```hcl\n   provider_installation {\n     dev_overrides {\n       \"grafbase/grafbase\" = \"/path/to/terraform-provider-grafbase\"\n     }\n     direct {}\n   }\n   ```\n\n3. **Use in your Terraform configuration:**\n   ```hcl\n   terraform {\n     required_providers {\n       grafbase = {\n         source = \"grafbase/grafbase\"\n       }\n     }\n   }\n   ```\n\n### Debugging\n\nFor debugging the provider:\n\n```bash\ngo run . -debug\n```\n\nThis outputs instructions for setting `TF_REATTACH_PROVIDERS` environment variable.\n\nFor verbose Terraform logging:\n```bash\nexport TF_LOG=DEBUG\nterraform apply\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Failed**\n   - Verify your API key is correct\n   - Check that `GRAFBASE_API_KEY` environment variable is set\n   - Ensure the API key has the necessary permissions\n\n2. **Account Not Found**\n   - Verify the account slug is correct\n   - Check that you have access to the specified account\n\n3. **Graph Already Exists**\n   - Graph slugs must be unique within an account\n   - Use `terraform import` to import existing graphs\n\n4. **Provider Not Found**\n   - Ensure you've run `terraform init`\n   - Check your `.terraformrc` configuration for local development\n\n### Debug Steps\n\n1. Enable debug logging:\n   ```bash\n   export TF_LOG=DEBUG\n   ```\n\n2. Check provider installation:\n   ```bash\n   terraform version\n   ```\n\n3. Validate configuration:\n   ```bash\n   terraform validate\n   ```\n\n4. Test API connectivity:\n   ```bash\n   curl -H \"Authorization: Bearer $GRAFBASE_API_KEY\" \\\n        -H \"Content-Type: application/json\" \\\n        -d '{\"query\": \"query { __schema { queryType { name } } }\"}' \\\n        https://api.grafbase.com/graphql\n   ```\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork the repository**\n2. **Create a feature branch:**\n   ```bash\n   git checkout -b feature/my-new-feature\n   ```\n3. **Make your changes**\n4. **Add tests** for new functionality\n5. **Run the test suite:**\n   ```bash\n   make test\n   ```\n6. **Format your code:**\n   ```bash\n   make fmt\n   ```\n7. **Submit a pull request**\n\n### Contribution Guidelines\n\n- Follow Go best practices and conventions\n- Add tests for new features and bug fixes\n- Update documentation for user-facing changes\n- Use descriptive commit messages\n- Ensure all tests pass before submitting\n\n### Development Workflow\n\n1. Make changes to the code\n2. Run `make build` to build the provider\n3. Run `make test` to run unit tests\n4. Test manually with example configurations\n5. Run `make fmt` to format code\n6. Submit pull request\n\n## License\n\nThis project is licensed under the Mozilla Public License 2.0. See the [LICENSE](LICENSE) file for details.\n\n## Support\n\n### Community Support\n\n- **GitHub Issues**: [Report bugs and request features](https://github.com/grafbase/terraform-provider-grafbase/issues)\n\n### Grafbase Support\n\n- **Documentation**: [Grafbase Docs](https://grafbase.com/docs)\n- **Community**: [Grafbase Discord](https://grafbase.com/discord)\n\n### Reporting Issues\n\nWhen reporting issues, please include:\n\n1. Terraform version (`terraform version`)\n2. Provider version\n3. Operating system and architecture\n4. Relevant Terraform configuration (sanitized)\n5. Error messages or unexpected behavior\n6. Steps to reproduce\n\n### Security\n\nFor security vulnerabilities, please email [security@grafbase.com](mailto:security@grafbase.com) instead of creating a public issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafbase%2Fterraform-provider-grafbase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafbase%2Fterraform-provider-grafbase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafbase%2Fterraform-provider-grafbase/lists"}