Skip to content

Latest commit

 

History

History
233 lines (153 loc) · 8.95 KB

CONTRIBUTING.md

File metadata and controls

233 lines (153 loc) · 8.95 KB
Raw

Contributing to GitLab Terraform Provider

Thank you for contributing to this provider! 🎉 ❤️ 🏆

Generally we accept any change that adds or changes a Terraform resource that is in line with the GitLab API. It is always best to open an issue before starting on a change.

Getting Started

Use HashiCorp's Plugin Development guide as a reference, especially the Provider Design Principles.

See the Developing The Provider section below for specifics about this GitLab provider.

Before Committing

Run make reviewable and include any generated files in your commit. This will help ensure your PR passes automated checks.

PR Checklist

For a smooth review process, please run through this checklist before submitting a PR.

  1. Resource attributes match 1:1 the names and structure of the API resource in the GitLab API documentation.
  2. Examples are updated with:
    1. A *.tf file for the resource/s with at least one usage example
    2. A *.sh file for the resource/s with an import example (if applicable)
  3. New resources have at minimum a basic test with three steps:
    1. Create the resource
    2. Update the attributes
    3. Import the resource
  4. No new //lintignore comments that came from copied code. Linter rules are meant to be enforced on new code.

Guidelines

Resource ID and Import

Terraform resources have a unique ID (d.SetId("")). The ID should be comprised from the URL path variables of the GET API for the resource in the GitLab API documentation, separated by :.

For example, a resource for the GET /projects/:id/environments/:environment_id API would have the ID 123:456 where 123 is the project ID and 456 is the environment ID.

This makes it very easy to add import functionality, by using

Importer: &schema.ResourceImporter{
    StateContext: schema.ImportStatePassthroughContext,
},

See the importer state function docs for more details.

Documentation

Documentation in /docs is auto-generated by terraform-plugin-docs based on code descriptions and examples. Generation runs during make reviewable. You can use the Terraform doc preview tool if you would like to preview the generated documentation.

Developing The Provider

Set Up Your Local Environment

You'll first need Go installed on your machine (version 1.19+ is required).

  1. Clone the git repository.

    $ git clone git@github.com:gitlabhq/terraform-provider-gitlab
$ cd terraform-provider-gitlab

  2. Build the provider with make build. This will build the provider and put the provider binary in the $GOPATH/bin directory.

    $ make build

You can also install the provider locally so that you can use it with Terraform experimentally. Run one of the following make commands depending on what is correct for your platform:

# Default: suitable for macOS
make local

# Set the terraform platform directory
# e.g. for linux amd64:
make local TERRAFORM_PLATFORM_DIR=linux_amd64

# Set the terraform plugin dir, see https://www.terraform.io/cli/config/config-file#implied-local-mirror-directories
# e.g. for Windows
make local TERRAFORM_PLUGIN_DIR=%APPDATA%/terraform.d/plugins

The you can use it in your provider config like this:

terraform {
  required_providers {
    gitlab = {
      version = "99.99.99"
      source  = "gitlab.local/x/gitlab"
    }
  }
}

M1/M2 Environments

The apple silicon environments currently have an issue where the local GitLab container will not start to run tests. We recommend that you use GitPod for developing the provider until this issue is resolved. If you manage to get a mac environment working properly, please let us know by creating an issue!

Use a Remote Environment via GitPod

You can choose to use your own development environment if desired, however a .gitpod.yml file is included within the repository to allow the use of GitPod easily. This will allow you to use GitPod's integration with GitHub to quickly start a web-based development environment including Go and Docker, which are necessary for running tests. To use GitPod's integration, you have two different options described below. After you've completed one of the two options, your development environment will be ready within a minute or two. As part of starting up, your development environment will automatically start up the gitlab-ce container necessary for running tests, as described in the "Running Tests/Option 1" section below.

Option 1: Manually navigate to GitPod

You can manually sign in and open your workspace within GitPod by following these steps:

  1. Navigate to GitPod
  2. Click Login if you have an account, or Sign Up if you do not.
  3. Click on "Continue with GitHub" and authorize GitPod to access your account.
  4. After you've signed in, select "Projects" along the top menu, click on your forked terraform-provider-gitlab project
  5. Hover over either the main branch for your fork or the branch you created for your fork, and click "New Workspace"

Option 2: Open your GitPod Workspace directly via URL

  1. Navigate to your fork of the terraform-provider-gitlab project in GitHub
  2. Select the branch you want to develop
  3. Add https://gitpod.io/# to the front of your URL

Your workspace will automatically open the repository and branch that you selected in GitHub.

Running Tests

The acceptance tests can run against a Gitlab instance where you have a token with administrator permissions (likely not gitlab.com).

The GitHub Actions test against the three latest GitLab releases.

Option 1: Run tests against a local Gitlab container with docker-compose

This option is the easiest and requires docker-compose (version 1.13+) to be installed on your machine.

Note that the you need an up-to-date version of GNU make and an up-to-date version of openssl / libressl.

  1. Start the Gitlab container. It will take about 5 minutes for the container to become healthy.
$ make testacc-up
  1. Run the acceptance tests. The full suite takes 10-20 minutes to run.
$ make testacc
  1. Stop the Gitlab container.
$ make testacc-down

Option 2: Run tests against your own Gitlab instance

If you have your own hosted Gitlab instance, you can run the tests against it directly.

$ make testacc GITLAB_TOKEN=example123 GITLAB_BASE_URL=https://example.com/api/v4

GITLAB_TOKEN must be a valid token for an account with admin privileges.

Testing Tips

  • Gitlab Community Edition and Gitlab Enterprise Edition:

    This module supports both Gitlab CE and Gitlab EE. We run tests on Gitlab EE, but can't run them on pull requests from forks.

    Features that only work on one flavour can use the following helpers as SkipFunc: isRunningInEE and isRunningInCE. You can see an example of this for gitlab_project_level_mr_approvals tests.

  • Run EE tests:

    If you have a Gitlab-license.txt you can run Gitlab EE, which will enable the full suite of tests:

    $ make testacc-up SERVICE=gitlab-ee

  • Run tests against specific GitLab version:

    Specify the GitLab release in the GITLAB_CE_VERSION or GITLAB_EE_VERSION, e.g.:

    $ make testacc-up GITLAB_CE_VERSION=15.0.0-ce.0

  • Run a single test:

    You can pass a pattern to the RUN variable to run a reduced number of tests. For example:

    $ make testacc RUN=TestAccGitlabGroup

    ...will run all tests for the gitlab_group resource.

  • Debug a test in an IDE:

    First start the Gitlab container with make testacc-up. Then run the desired Go test as you would normally from your IDE, but configure your run configuration to set these environment variables:

    GITLAB_TOKEN=ACCTEST1234567890123
GITLAB_BASE_URL=http://127.0.0.1:8080/api/v4
TF_ACC=1

  • Useful HashiCorp documentation:

    Refer to HashiCorp's testing guide and HashiCorp's testing best practices.