Skip to content

Commit 4b72df7

Browse files
fabiomatavelli-f3fabiomatavelli-f3
committed
docs: update readme
1 parent 9a6e8c2 commit 4b72df7

File tree

1 file changed

+87
-39
lines changed

1 file changed

+87
-39
lines changed

‎README.md‎

Lines changed: 87 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,49 @@
11
# terraform-provider-githubfile
22

33
[![Build status](https://github.com/form3tech-oss/terraform-provider-githubfile/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/form3tech-oss/terraform-provider-githubfile/actions)
4+
[![License](https://img.shields.io/github/license/form3tech-oss/terraform-provider-githubfile)](LICENSE)
45

56
A Terraform provider for managing files in GitHub repositories.
67

7-
## Use-cases
8+
## Use Cases
89

9-
A few possible use-cases for `terraform-provider-githubfile` are:
10+
A few possible use cases for `terraform-provider-githubfile` are:
1011

1112
* Adding a `LICENSE` file to a number of repositories.
1213
* Making sure repositories across an organisation have consistent issue/pull request templates.
13-
* Configuring a tool such as [`golangci-lint`](https://github.com/golangci/golangci-lint) or [`pre-commit`](https://pre-commit.com/) uniformly across a number of repositories
14+
* Configuring a tool such as [`golangci-lint`](https://github.com/golangci/golangci-lint) or [`pre-commit`](https://pre-commit.com/) uniformly across a number of repositories.
1415

1516
## Installation
1617

17-
Download the relevant binary from [releases](https://github.com/form3tech-oss/terraform-provider-github-file/releases) and copy it to `$HOME/.terraform.d/plugins/`.
18+
### Manual Installation
19+
20+
Download the relevant binary from [releases](https://github.com/form3tech-oss/terraform-provider-githubfile/releases) and copy it to `$HOME/.terraform.d/plugins/`.
1821

1922
## Configuration
2023

2124
The following provider block variables are available for configuration:
2225

23-
| Name | Description |
24-
| ---- | ----------- |
25-
| `commit_message_prefix` | An optional prefix to be added to all commits generated as a result of manipulating files. |
26-
| `github_email` | The email address to use for commit messages.<br>If a GPG key is provided, this must match the one which the key corresponds to. |
27-
| `github_token` | A GitHub authorisation token with `repo` permissions and having `admin` access to the target repositories. |
28-
| `github_username` | The username to use for commit messages. |
29-
| `gpg_passphrase` | The passphrase associated with the provided `gpg_secret_key` (see below). |
30-
| `gpg_secret_key` | The GPG secret key to be use for commit signing.<br>If left empty, commits will not be signed. |
26+
| Name | Required | Environment Variable | Description |
27+
| ---- | :------: | -------------------- | ----------- |
28+
| `github_token` | **Yes** | `GITHUB_TOKEN` | A GitHub authorisation token with permissions to manage files in the target repositories. |
29+
| `github_email` | **Yes** | `GITHUB_EMAIL` | The email address to use for commit messages. If a GPG key is provided, this must match the one which the key corresponds to. |
30+
| `github_username` | **Yes** | `GITHUB_USERNAME` | The username to use for commit messages. |
31+
| `commit_message_prefix` | No | `COMMIT_MESSAGE_PREFIX` | An optional prefix to be added to all commits generated as a result of manipulating files. |
32+
| `gpg_secret_key` | No | `GPG_SECRET_KEY` | The GPG secret key to use for commit signing. Accepts raw or base64-encoded values. If left empty, commits will not be signed. |
33+
| `gpg_passphrase` | No | `GPG_PASSPHRASE` | The passphrase associated with the provided `gpg_secret_key`. |
34+
35+
Each variable can be set either in the provider block or via the corresponding environment variable. Provider block values take precedence over environment variables.
36+
37+
### Example
3138

32-
Alternatively, these values can be read from environment variables.
39+
```hcl
40+
provider "githubfile" {
41+
github_token = var.github_token
42+
github_email = "ci-bot@example.com"
43+
github_username = "ci-bot"
44+
commit_message_prefix = "[terraform]"
45+
}
46+
```
3347

3448
## Resources
3549

@@ -39,44 +53,78 @@ The `githubfile_file` resource represents a file in a given branch of a GitHub r
3953

4054
#### Attributes
4155

42-
| Name | Description |
43-
| ---- | ----------- |
44-
| `repository_owner` | The owner of the repository. |
45-
| `repository_name` | The name of the repository. |
46-
| `branch` | The branch in which to create/update the file<br>Leaving this empty will cause the file to be created/updated in the default branch. |
47-
| `path` | The path to the file being created/updated. |
48-
| `contents` | The contents of the file. |
56+
| Name | Type | Required | Description |
57+
| ---- | :--: | :------: | ----------- |
58+
| `id` | String | Computed | The ID of the file resource (format: `owner/repo:branch:path`). |
59+
| `repository_owner` | String | **Yes** | The owner of the repository. Changing this forces a new resource. |
60+
| `repository_name` | String | **Yes** | The name of the repository. Changing this forces a new resource. |
61+
| `branch` | String | **Yes** | The branch in which to create/update the file. Changing this forces a new resource. |
62+
| `path` | String | **Yes** | The path to the file being created/updated. Changing this forces a new resource. |
63+
| `contents` | String | **Yes** | The contents of the file. |
64+
65+
> **Note:** When a managed file is in an archived repository, the provider will gracefully skip deletion and simply remove the resource from state.
4966
5067
#### Example
5168

5269
```hcl
53-
resource "githubfile_file" "form3tech_oss_terraform_provider_githubfile_issue_template" {
54-
repository_owner = "form3tech-oss"
55-
repository_name = "terraform-provider-githubfile"
56-
branch = ""
57-
path = ".github/ISSUE_TEMPLATE.md"
58-
contents = <<EOF
59-
# Issue Type
70+
resource "githubfile_file" "issue_template" {
71+
repository_owner = "form3tech-oss"
72+
repository_name = "terraform-provider-githubfile"
73+
branch = "main"
74+
path = ".github/ISSUE_TEMPLATE.md"
75+
contents = <<-EOF
76+
# Issue Type
6077
61-
- [ ] Bug report.
62-
- [ ] Suggestion.
78+
- [ ] Bug report.
79+
- [ ] Suggestion.
6380
64-
# Description
81+
# Description
6582
66-
<!-- Please provide a description of the issue. -->
67-
EOF
83+
<!-- Please provide a description of the issue. -->
84+
EOF
6885
}
6986
```
7087

71-
Creating the resource above will result in the `.github/ISSUE_TEMPLATE.md` file being created/updated on the default branch of the `form3tech-oss/terraform-provider-githubfile` repository with the following contents:
88+
Creating the resource above will result in the `.github/ISSUE_TEMPLATE.md` file being created/updated on the `main` branch of the `form3tech-oss/terraform-provider-githubfile` repository.
89+
90+
#### Import
91+
92+
Existing files can be imported into Terraform state using the following ID format:
93+
94+
```
95+
owner/repo:branch:path
96+
```
97+
98+
For example:
99+
100+
```bash
101+
terraform import githubfile_file.issue_template form3tech-oss/terraform-provider-githubfile:main:.github/ISSUE_TEMPLATE.md
102+
```
103+
104+
## Development
72105

73-
```markdown
74-
# Issue Type
106+
### Requirements
75107

76-
- [ ] Bug report.
77-
- [ ] Suggestion.
108+
* [Go](https://golang.org/dl/) (see `go.mod` for the required version)
109+
* A GitHub token with `repo` permissions (set as `GITHUB_TOKEN`)
78110

79-
# Description
111+
### Building
80112

81-
<!-- Please provide a description of the issue. -->
113+
```bash
114+
make build
82115
```
116+
117+
### Running Tests
118+
119+
Acceptance tests require a valid GitHub token and run against the `form3tech-oss/terraform-provider-githubfile` repository:
120+
121+
```bash
122+
export GITHUB_TOKEN="your-token"
123+
export GITHUB_EMAIL="your-email@example.com"
124+
export GITHUB_USERNAME="your-username"
125+
make test
126+
```
127+
128+
## License
129+
130+
This project is licensed under the [Apache License 2.0](LICENSE).

0 commit comments

Comments
 (0)