|
1 | | -## Release Flow |
| 1 | +# Release Process |
2 | 2 |
|
3 | | -The release process uses GitHub Actions and [`goreleaser`](https://github.com/goreleaser/goreleaser) to build, sign, and upload provider binaries to a GitHub release. Release are triggered by a tag with the pattern `v*` (e.g. `v1.2.3`); these tags may only be created from the default branch (`main`) or branches that match the pattern `release-v*`. |
| 3 | +This document describes the release pipeline for `vmvarela/github`, published to both the |
| 4 | +[Terraform Registry](https://registry.terraform.io/providers/vmvarela/github) and the |
| 5 | +[OpenTofu Registry](https://search.opentofu.org/provider/vmvarela/github). |
4 | 6 |
|
5 | | -The release flow is as follows: |
| 7 | +## Versioning |
6 | 8 |
|
7 | | -[!IMPORTANT] |
8 | | -> In you're planning on releasing a major version, please ensure you've completed the following tasks: |
9 | | -> |
10 | | -> - Read Hashicorp guidance on [incrementing the major version](https://developer.hashicorp.com/terraform/plugin/best-practices/versioning#example-major-number-increments). |
11 | | -> - Check if there are any outstanding [PRs with breaking changes](https://github.com/integrations/terraform-provider-github/issues?q=state%3Aopen%20label%3A%22Type%3A%20Breaking%20change%22) that could be included in the release. |
12 | | -> - Check that all deprecations have been addressed and removed from the codebase. |
| 9 | +This fork uses **CalVer** (`vYY.MM.N`) to avoid conflicts with upstream SemVer tags (`v6.x.x`): |
13 | 10 |
|
14 | | -1. Navigate to the [repository's Releases page](https://github.com/integrations/terraform-provider-github/releases) and click _Draft a new release_. |
15 | | -1. Create a new [SemVer](https://semver.org/) tag for the release. |
16 | | -1. Select the target as either the default branch (`main`) or a release branch (a branch matching the pattern `release-v*`) |
17 | | -1. Click _Generate release notes_. |
18 | | -1. If this release is from a release branch (unless it really is the latest release) uncheck the _Set as the latest release_ checkbox. |
19 | | -1. Click "Publish release". |
20 | | -1. GitHub Actions will trigger the [release workflow](https://github.com/integrations/terraform-provider-github/actions/workflows/release.yaml). |
| 11 | +| Field | Meaning | Example | |
| 12 | +|-------|---------|---------| |
| 13 | +| `YY` | 2-digit year | `26` | |
| 14 | +| `MM` | Month (no zero-pad) | `3` | |
| 15 | +| `N` | Sequential release within the month, starting at 0 | `0` | |
21 | 16 |
|
22 | | -After the workflow executes successfully, the GitHub release created in the prior step will have the relevant assets available for consumption and the new version will show up in the [Terraform Registry](https://registry.terraform.io/providers/integrations/github/latest). |
| 17 | +Examples: `v26.3.0`, `v26.3.1`, `v26.4.0` |
| 18 | + |
| 19 | +## One-Time Setup |
| 20 | + |
| 21 | +### 1. GPG Signing Key |
| 22 | + |
| 23 | +The Terraform Registry requires provider binaries to be signed with a GPG key. The public key must |
| 24 | +be registered in your Terraform Registry account, and the private key must be stored as a repository |
| 25 | +secret. |
| 26 | + |
| 27 | +```bash |
| 28 | +# Generate a new GPG key (RSA 4096, no expiry) |
| 29 | +gpg --full-generate-key |
| 30 | + |
| 31 | +# Export the private key (base64-encoded, for the secret) |
| 32 | +gpg --export-secret-keys --armor <KEY_ID> | base64 |
| 33 | + |
| 34 | +# Export the public key (to register in the Terraform Registry) |
| 35 | +gpg --export --armor <KEY_ID> |
| 36 | +``` |
| 37 | + |
| 38 | +Register the **public key** at: |
| 39 | +- Terraform Registry: Settings → GPG Keys → Add a GPG key |
| 40 | + (`https://registry.terraform.io/settings/gpg-keys`) |
| 41 | +- OpenTofu Registry: follows the same Terraform Registry protocol; no separate key registration |
| 42 | + is needed |
| 43 | + |
| 44 | +### 2. GitHub Repository Secrets |
| 45 | + |
| 46 | +Store the following secrets under **Settings → Environments → `release`** in this repository: |
| 47 | + |
| 48 | +| Secret | Value | |
| 49 | +|--------|-------| |
| 50 | +| `GPG_PRIVATE_KEY` | Base64-encoded private GPG key from the step above | |
| 51 | +| `PASSPHRASE` | Passphrase used when generating the GPG key | |
| 52 | + |
| 53 | +The `release` environment is referenced by `.github/workflows/release.yaml` and gates the signing |
| 54 | +step. |
| 55 | + |
| 56 | +### 3. Register the Provider |
| 57 | + |
| 58 | +**Terraform Registry** (`registry.terraform.io`): |
| 59 | + |
| 60 | +1. Sign in at <https://registry.terraform.io> with your GitHub account. |
| 61 | +2. Click **Publish → Provider**. |
| 62 | +3. Select the `vmvarela/terraform-provider-github` repository. |
| 63 | +4. Confirm the GPG public key is already registered (step 1 above). |
| 64 | +5. Click **Publish Provider**. |
| 65 | + |
| 66 | +The registry will detect the first CalVer tag (`v26.x.x`) automatically on the next push. |
| 67 | + |
| 68 | +**OpenTofu Registry** (`search.opentofu.org`): |
| 69 | + |
| 70 | +The OpenTofu Registry mirrors providers published to the Terraform Registry via the same GitHub |
| 71 | +release assets. No separate registration is required — once the Terraform Registry picks up a |
| 72 | +release, the OpenTofu Registry will index it automatically, provided the |
| 73 | +`terraform-registry-manifest.json` is included in the release (already configured in |
| 74 | +`.goreleaser.yml`). |
| 75 | + |
| 76 | +## Release Workflow |
| 77 | + |
| 78 | +### Normal Release (new CalVer tag on `master`) |
| 79 | + |
| 80 | +```bash |
| 81 | +# 1. Ensure master is up to date with upstream and all feature branches |
| 82 | +git checkout master |
| 83 | +git fetch upstream main |
| 84 | +git merge upstream/main |
| 85 | +git merge billing-usage |
| 86 | +git merge cost-centers |
| 87 | +git merge enterprise-scim |
| 88 | +git merge enterprise-teams |
| 89 | + |
| 90 | +# 2. Run the build and tests to confirm everything is green |
| 91 | +make build |
| 92 | +make test |
| 93 | + |
| 94 | +# 3. Create and push a CalVer tag |
| 95 | +# Format: vYY.MM.N (e.g. first release of April 2026 -> v26.4.0) |
| 96 | +git tag v26.4.0 |
| 97 | +git push origin master --tags |
| 98 | +``` |
| 99 | + |
| 100 | +The [release workflow](.github/workflows/release.yaml) triggers automatically on `v*` tags and: |
| 101 | + |
| 102 | +1. Builds binaries for all supported platforms (linux, darwin, windows, freebsd — amd64/arm64/386/arm) |
| 103 | +2. Generates an SBOM with Syft |
| 104 | +3. Signs the SHA256SUMS file with the GPG key from the `release` environment |
| 105 | +4. Signs the SBOM with Cosign (keyless, via OIDC) |
| 106 | +5. Creates a GitHub Release with all assets |
| 107 | +6. Attests build provenance with `actions/attest-build-provenance` |
| 108 | + |
| 109 | +Both registries poll GitHub Releases and will pick up the new version within minutes. |
| 110 | + |
| 111 | +### Patch Release (bug fix on current month) |
| 112 | + |
| 113 | +```bash |
| 114 | +# Increment only the patch counter |
| 115 | +git tag v26.4.1 |
| 116 | +git push origin master --tags |
| 117 | +``` |
| 118 | + |
| 119 | +### Feature Branch Merge Before Release |
| 120 | + |
| 121 | +When a feature branch has new commits that should be included in the next release: |
| 122 | + |
| 123 | +```bash |
| 124 | +git checkout master |
| 125 | +git merge <feature-branch> |
| 126 | +git push origin master |
| 127 | +# Then follow the normal release steps above |
| 128 | +``` |
| 129 | + |
| 130 | +## Branch Protection Notes |
| 131 | + |
| 132 | +- **`main`** tracks `upstream/main` — never commit here directly. |
| 133 | +- **`master`** is the integration and release branch — all tags must be pushed from here. |
| 134 | +- Feature branches (`billing-usage`, `cost-centers`, `enterprise-scim`, `enterprise-teams`) each |
| 135 | + have an open PR against upstream. Keep them rebased on `upstream/main`. |
| 136 | + |
| 137 | +## Verifying a Release |
| 138 | + |
| 139 | +After the workflow completes: |
| 140 | + |
| 141 | +```bash |
| 142 | +# Verify the GitHub release assets exist |
| 143 | +gh release view v26.4.0 |
| 144 | + |
| 145 | +# Confirm the provider appears in the Terraform Registry (may take a few minutes) |
| 146 | +curl -s https://registry.terraform.io/v1/providers/vmvarela/github/versions | jq '.versions[-1].version' |
| 147 | + |
| 148 | +# Verify build attestation |
| 149 | +gh attestation verify ./dist/terraform-provider-github_v26.4.0_linux_amd64.zip \ |
| 150 | + --repo vmvarela/terraform-provider-github |
| 151 | +``` |
| 152 | + |
| 153 | +Full attestation verification instructions are in [VERIFY_ATTESTATIONS.md](VERIFY_ATTESTATIONS.md). |
0 commit comments