|
1 | 1 | # ghsecrets |
2 | 2 |
|
3 | | -ghsecrets is a command-line tool designed to manage and set test secrets in GitHub via the GitHub CLI. |
| 3 | +`ghsecrets` is a command-line tool designed to manage and set test secrets in either: |
| 4 | + |
| 5 | +- **GitHub** (via the GitHub CLI), or |
| 6 | +- **AWS Secrets Manager**. |
| 7 | + |
| 8 | +This tool helps streamline the process of storing test secrets which can be referenced by your workflows or other services. |
| 9 | + |
| 10 | +--- |
4 | 11 |
|
5 | 12 | ## Installation |
6 | 13 |
|
7 | | -To install ghsecrets CLI, you need to have Go installed on your machine. With Go installed, run the following command: |
| 14 | +To install the `ghsecrets` CLI, ensure you have Go installed. Then run: |
8 | 15 |
|
9 | 16 | ```sh |
10 | 17 | go install github.com/smartcontractkit/chainlink-testing-framework/tools/ghsecrets@latest |
11 | 18 | ``` |
12 | 19 |
|
13 | | -Please install GitHub CLI to use this tool - https://cli.github.com/ |
| 20 | +Note: If you plan to set secrets in GitHub, please also install the GitHub CLI (gh). |
14 | 21 |
|
15 | 22 | ## Usage |
16 | 23 |
|
17 | | -Set default test secrets from ~/.testsecrets file: |
| 24 | +### 1. Setting Secrets |
| 25 | + |
| 26 | +By default, `ghsecrets set` assumes you want to store secrets in AWS Secrets Manager, using a file from `~/.testsecrets` (if not specified). You can change the backend to GitHub, specify a custom file path, or share the AWS secret with other IAM principals. Below are common examples: |
| 27 | + |
| 28 | +#### a) Set secrets in AWS (default) |
| 29 | + |
| 30 | +> **⚠️ Note:** Ensure you authenticate with AWS before using the tool: |
| 31 | +> |
| 32 | +> ```sh |
| 33 | +> aws sso login --profile <your-aws-sdlc-profile> |
| 34 | +> ``` |
| 35 | +> Use the **SDLC** profile in AWS |
| 36 | +
|
| 37 | +This will read from `~/.testsecrets` (by default) and create/update a secret in AWS Secrets Manager: |
| 38 | +
|
| 39 | +```sh |
| 40 | +ghsecrets set --profile <your-aws-sdlc-profile> |
| 41 | +``` |
| 42 | +
|
| 43 | +If you’d like to specify a different file: |
| 44 | + |
| 45 | +```sh |
| 46 | +ghsecrets set --file /path/to/mysecrets.env --profile <your-aws-sdlc-profile> |
| 47 | +``` |
| 48 | + |
| 49 | +If you’d like to specify a custom secret name: |
18 | 50 |
|
19 | 51 | ```sh |
20 | | -ghsecrets set |
| 52 | +ghsecrets set --secret-id my-custom-secret --profile <your-aws-sdlc-profile> |
| 53 | +``` |
| 54 | + |
| 55 | +Note: For AWS backend, the tool automatically adds the `testsecrets/` prefix if it is missing. This ensures consistency and allows GitHub Actions to access all secrets with this designated prefix. |
| 56 | + |
| 57 | +If you’d like to share this secret with additional AWS IAM principals (e.g., a collaborator’s account): |
| 58 | + |
| 59 | +```sh |
| 60 | +ghsecrets set --shared-with arn:aws:iam::123456789012:role/SomeRole --profile <your-aws-sdlc-profile> |
| 61 | +``` |
| 62 | + |
| 63 | +You can specify multiple ARNs using commas: |
| 64 | + |
| 65 | +```sh |
| 66 | +ghsecrets set --shared-with arn:aws:iam::123456789012:role/SomeRole,arn:aws:iam::345678901234:root --profile <your-aws-sdlc-profile> |
| 67 | +``` |
| 68 | + |
| 69 | +#### b) Set secrets in GitHub |
| 70 | + |
| 71 | +```sh |
| 72 | +ghsecrets set --backend github |
| 73 | +``` |
| 74 | + |
| 75 | +This will: |
| 76 | +1. Read from the default file (`~/.testsecrets`) unless `--file` is specified. |
| 77 | +2. Base64-encode the content. |
| 78 | +3. Create/update a GitHub secret using the GitHub CLI. |
| 79 | + |
| 80 | +### 2. Retrieving Secrets (AWS Only) |
| 81 | + |
| 82 | +If you want to retrieve an existing secret from AWS Secrets Manager, use: |
| 83 | + |
| 84 | +```sh |
| 85 | +ghsecrets get --secret-id testsecrets/MySecretName --profile <your-aws-sdlc-profile> |
| 86 | +``` |
| 87 | + |
| 88 | +By default, it tries to decode a Base64-encoded test secret. To disable decoding use `--decode false` flag: |
| 89 | + |
| 90 | +```sh |
| 91 | +ghsecrets get --secret-id testsecrets/MySecretName --decode false --profile <your-aws-sdlc-profile> |
21 | 92 | ``` |
22 | 93 |
|
23 | 94 | ## FAQ |
24 | 95 |
|
25 | | -### Q: What should I do if I get "command not found: ghsecrets" after installation? |
| 96 | +<details> |
| 97 | +<summary><strong>Q: I get "command not found: ghsecrets" after installation. How do I fix this?</strong></summary> |
| 98 | + |
| 99 | +This error typically means the directory where Go installs its binaries is not in your system’s PATH. The binaries are usually installed in `$GOPATH/bin` or `$GOBIN`. |
| 100 | + |
| 101 | +Steps to fix: |
| 102 | +1. If you use `asdf`, run: |
| 103 | + |
| 104 | + ```sh |
| 105 | + asdf reshim golang |
| 106 | + ``` |
| 107 | + |
| 108 | +2. Otherwise, add your Go bin directory to PATH manually: |
| 109 | + - Find your Go bin directory: |
| 110 | + |
| 111 | + ```sh |
| 112 | + echo $(go env GOPATH)/bin |
| 113 | + ``` |
| 114 | + |
| 115 | + - Add it to your shell config (e.g., `~/.bashrc`, `~/.zshrc`): |
| 116 | + |
| 117 | + ```sh |
| 118 | + export PATH="$PATH:<path-to-go-bin>" |
| 119 | + ``` |
| 120 | + |
| 121 | + - Reload your shell: |
26 | 122 |
|
27 | | -This error typically means that the directory where Go installs its binaries is not included in your system's PATH. The binaries are usually installed in $GOPATH/bin or $GOBIN. Here's how you can resolve this issue: |
| 123 | + ```sh |
| 124 | + source ~/.bashrc # or .zshrc, etc. |
| 125 | + ``` |
28 | 126 |
|
29 | | -1. If you use `asdf` run `asdf reshim golang` |
| 127 | +3. Alternatively, run the tool using its full path without modifying PATH: |
30 | 128 |
|
31 | | -2. Or, add Go bin directory to PATH: |
| 129 | + ```sh |
| 130 | + $(go env GOPATH)/bin/ghsecrets set |
| 131 | + ``` |
32 | 132 |
|
33 | | -- First, find out where your Go bin directory is by running: |
| 133 | +</details> |
34 | 134 |
|
35 | | - ```sh |
36 | | - echo $(go env GOPATH)/bin |
37 | | - ``` |
| 135 | +<details> |
| 136 | +<summary><strong>Q: What if my AWS SSO session expires?</strong></summary> |
| 137 | + |
| 138 | +If you see errors like `InvalidGrantException` when setting or retrieving secrets from AWS, your SSO session may have expired. Re-authenticate using: |
| 139 | + |
| 140 | +```sh |
| 141 | +aws sso login --profile <my-aws-profile> |
| 142 | +``` |
| 143 | + |
| 144 | +Then try running `ghsecrets` again. |
| 145 | + |
| 146 | +</details> |
| 147 | + |
| 148 | +<details> |
| 149 | +<summary><strong>Q: What if I get an error that says "GitHub CLI not found"?</strong></summary> |
| 150 | + |
| 151 | +For GitHub secrets, this tool requires the GitHub CLI. Please install it first: |
| 152 | + |
| 153 | +```sh |
| 154 | +brew install gh |
| 155 | +# or |
| 156 | +sudo apt-get install gh |
| 157 | +``` |
| 158 | + |
| 159 | +Then run: |
| 160 | + |
| 161 | +```sh |
| 162 | +gh auth login |
| 163 | +``` |
38 | 164 |
|
39 | | - This command will print the path where Go binaries are installed, typically something like /home/username/go/bin |
| 165 | +and follow the prompts to authenticate. |
40 | 166 |
|
41 | | -- Add the following line at the end of your shell config file (`.bashrc`, `.zshrc`), usually located at `~/`: |
| 167 | +</details> |
42 | 168 |
|
43 | | - ```sh |
44 | | - export PATH="$PATH:<path-to-go-bin>" |
45 | | - ``` |
| 169 | +## Contributing |
46 | 170 |
|
47 | | -- Apply the changes by sourcing the file: |
48 | | - ```sh |
49 | | - source ~/.bashrc # Use the appropriate file like .zshrc if needed |
50 | | - ``` |
| 171 | +Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change. |
51 | 172 |
|
52 | | -3. Alternatively, run using the full path: |
| 173 | +## License |
53 | 174 |
|
54 | | - If you prefer not to alter your PATH, or if you are troubleshooting temporarily, you can run the tool directly using its full path: |
| 175 | +This project is licensed under the MIT License. Feel free to use, modify, and distribute it as needed. |
55 | 176 |
|
56 | | - ```sh |
57 | | - $(go env GOPATH)/bin/ghsecrets set |
58 | | - ``` |
|
0 commit comments