/terraform-provider-github

Terraform GitHub provider

Primary LanguageGoMozilla Public License 2.0MPL-2.0

Terraform Provider

Requirements

  • Terraform 0.10.x
  • Go 1.11 (to build the provider plugin)

Building The Provider

Clone repository to: $GOPATH/src/github.com/terraform-providers/terraform-provider-github

$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
$ git clone git@github.com:terraform-providers/terraform-provider-github.git

Enter the provider directory and build the provider

$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
$ make build
# or if you're on a mac:
$ gnumake build

Using the provider

Detailed documentation for the GitHub provider can be found here.

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.11+ is required). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

To compile the provider, run make build. This will build the provider and put the provider binary in the $GOPATH/bin directory.

$ make build
...
$ $GOPATH/bin/terraform-provider-github
...

In order to test the provider, you can simply run make test.

$ make test

In order to run the full suite of Acceptance tests, run make testacc.

Note: Acceptance tests create real resources, and often cost money to run.

$ make testacc

Acceptance test prerequisites

In order to successfully run the full suite of acceptance tests, you will need to have the following:

GitHub personal access token

You will need to create a personal access token for testing. It will need to have the following scopes selected:

  • repo
  • admin:org
  • admin:public_key
  • admin:repo_hook
  • admin:org_hook
  • user
  • delete_repo
  • admin:gpg_key

Once the token has been created, it must be exported in your environment as GITHUB_TOKEN.

GitHub organization

If you do not have an organization already that you are comfortable running tests again, you will need to create one. The free "Team for Open Source" org type is fine for these tests. The name of the organization must then be exported in your environment as GITHUB_ORGANIZATION.

Test repository

In the organization you are using above, create a test repository named test-repo. Make sure the repository is configured as follows:

  • The description should be Test description, used in GitHub Terraform provider acceptance test.
  • The website url should be http://www.example.com
  • Create two topics within the repo named test-topic and second-test-topic
  • In the repo settings, make sure all features and merge button options are enabled.

GitHub users

Export your github username (the one you used to create the personal access token above) as GITHUB_TEST_USER. You will need to export a different github username as GITHUB_TEST_COLLABORATOR. Please note that these usernames cannot be the same as each other, and both of them must be real github usernames. The collaborator user does not need to be added as a collaborator to your test repo or organization, but as the acceptance tests do real things (and will trigger some notifications for this user), you should probably make sure the person you specify knows that you're doing this just to be nice.