terraform-provider-circleci

README

(Unofficial) Terraform Provider for CircleCI

Usage

To use this provider, refer to https://registry.terraform.io/providers/kelvintaywl/circleci/latest

The rest of the README is mainly focused on how to develop on this source code.

Support status

Provider Block	Status	Remarks
api_token	Done ✅	$CIRCLE_TOKEN supported
hostname	Done ✅	$CIRCLE_HOSTNAME supported

Data Source	Status	Remarks
Webhooks	Done ✅
Project	Done ✅
Checkout keys	Done ✅
Context	Done ✅
Runner Resource-Classes	Done ✅
Runner Tokens	Done ✅

Resource	Status	Import supported?
Webhook	Done ✅	✅
Schedule	Done ✅	✅
Project	Done ✅
Project Environment Variable	Done ✅
Checkout key	Done ✅
Context	Done ✅	✅
Context Environment variable	Done ✅
Runner Resource-class	Done ✅	✅
Runner Token	Done ✅

Example

See sandbox

Development

# this project uses go 1.19
$ go mod download

# or, if you want to upgrade the Go dependencies too
$ go get -u
$ go mod tidy

# to build the go binary, and "install" to your local provider directory
# NOTE: this is a one-time action
$ make init

# whenever we make changes to the code
$ make build
# this then tries to terraform apply the sandbox
$ make tf.plan

# when you are ready to apply
$ make tf.apply

# destroy, as needed
$ make tf.destroy

Testing

We run acceptance tests against an actual CircleCI organizations and projects:

Type	Org	Project
GitHub OAuth	https://github.com/kelvintaywl-tf	https://github.com/kelvintaywl-tf/tf-provider-acceptance-test-dummy
Gitlab (standalone)	https://gitlab.com/ktwl411/	https://gitlab.com/ktwl411/loren-ipsum

# Run acceptance tests
$ export CIRCLE_TOKEN="user API token that can manage the organization and project"
$ make testacc

This is so as to contain the "blast radius" of the acceptance tests. In worst case, this organization and project is affected, but not more.

In addition, the CircleCI API token used belongs to a user that is not tied to my main CircleCI user account.

Docs

# to generate docs
# check docs/index.md
$ make docs

See docs

Releasing

Currently, we release locally with GoReleaser. The config can be found in .goreleaser.yml

# NOTE: make sure documents are generated!

# tag release
$ git tag vX.Y.Z -m "some message"

# install GoReleaser on MacOS if required
# See https://goreleaser.com/install/
$ brew install goreleaser/tap/goreleaser

# set required env vars
$ export GITHUB_TOKEN="your GitHub Token value, with public_repo scope required"
$ export GPG_FINGERPRINT="your GPG fingerprint, registered to your Terraform namespace"
# optional
$ export GPG_TTY=$(tty)

# make a GitHub release (with artifacts),
# via GoReleaser
$ goreleaser release --clean

Notes

This depends on a CircleCI Go SDK I (auto) generated: https://github.com/kelvintaywl/circleci-go-sdk

Why this is taking longer than I expected

1. I am unfortunately not a Go programmer. See Hashicorp's stance on support for other languages here
2. There is a template you are encouraged to use but the internal implementation is missing, so not knowing how to use the framework and Go makes it tougher.
3. The provided framework (SDK) is new, so older providers are not using it, which also makes it difficult to refer to example codes.