Skip to content

Commit 3181e8c

Browse files
aasmal97aasmal97
committed
updated readme
1 parent c7eb13d commit 3181e8c

1 file changed

Lines changed: 37 additions & 132 deletions

File tree

‎README.md‎

Lines changed: 37 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,70 @@
1-
# Hashicorp Vault Secrets Github Action
1+
# Authorized Github Actor Github Action
22

33
## Introduction
44

5-
Currently, [Hashicorp Vault Secrets](https://developer.hashicorp.com/hcp/docs/vault-secrets) has a direct one-click intergation that links a Github Repo to an app of their choosing.
5+
Currently, Github allows repositories to be protected using rulesets, according to an organization member's role, or individual roles.
66

7-
However, as highlighted by their [documentation](https://developer.hashicorp.com/hcp/docs/vault-secrets/integrations/github-actions), there are severe limitations. For example:
7+
However, rulesets for organizations are only enforced on a paid plan, which is not be reasonable for small teams.
88

9-
1. You can only sync secrets from a single Hashicorp Cloud Platform project
10-
2. You can only sync a single organization with a repository.
11-
3. This integration requires the Hashicorp Vault Secrets App to be installed and configured in your repository
12-
- This is not possible if the repository lives in an organization and the user is not a Github organization owner/admin.
9+
In addition Github Actions themselves, responsible for CI/CD pipelines or different automated tasks, sometimes need protection as well.
1310

14-
This action provides a solution for the aforementioned problems, by using a service principal on your HashiCorp Cloud Platform account, to programmatically access Hashicorp Vault secrets in a Github action runner, and pass them into your workflows.
15-
16-
## Configuring a Service Principal
17-
18-
### Requirements:
19-
20-
- You must be using a HCP Vault Secrets App
21-
- You must be a HashiCorp Cloud Platform organization Admin or Owner
22-
23-
### Steps:
24-
25-
1. Go [here](https://portal.cloud.hashicorp.com/sign-in) and login
26-
2. Go to your organization
27-
3. Go to **Access Control IAM**. Go to **Service Principals** and create a service principal account
28-
29-
##### Service Princpal Page Example
30-
31-
![Example of Sevice Princpal Landing Page](./images/Service_Principal.png)
11+
This action provides potential solutions for these cases. By detecting the Github actor that triggers the workflow, we can progammatically control and protect, branches (with additional steps) or steps in a Github action from only being triggered by certain users.
3212

3313
## Action Usage
3414

3515
### Quickstart
3616

3717
```yaml
38-
name: Hashicorp Vault Secrets
39-
uses: aasmal97/HashicorpVaultSecrets@v1.2.0
18+
name: Authorized Actor
19+
uses: aasmal97/AuthorizedActor@v1.0.0
4020
with:
41-
CLIENT_ID: ${{ secrets.HASHICORP_CLIENT_ID }}
42-
CLIENT_SECRET: ${{ secrets.HASHICORP_CLIENT_SECRET }}
43-
ORGANIZATION_NAME: "example-org"
44-
PROJECT_NAME: "example-project"
45-
APP_NAME: "ci-cd-pipeline-app"
46-
SECRET_NAMES: '["EXAMPLE_ID"]'
21+
authorizedActors: ${{secrets.AUTHORIZED_ACTORS}}
4722
```
4823
4924
### Inputs:
25+
- ##### githubOrg: `string` (optional)
26+
27+
- GitHub organization name, that you want to use to control acces
5028

51-
- ##### CLIENT_ID: `string` (required)
52-
- This is the Organization Service Principal's generated CLIENT_ID acquired from your Hashicorp Portal.
53-
- ##### CLIENT_SECRET: `string` (required)
54-
- This is the Organization Service Principal's generated CLIENT_SECRET acquired from your Hashicorp Portal.
55-
- ##### ORGANIZATION_NAME: `string` (required)
56-
- This is the Organization ID or Name that the Service Principal was created on
57-
- ##### PROJECT_NAME: `string` (required)
58-
- This is the project name that holds the apps where the secrets are stored
59-
- ##### APP_NAME: `string` (required)
60-
61-
- This is the app name, that holds the secrets
62-
63-
- ##### SECRET_NAMES: `string` (optional)
64-
65-
- This is **JSON Stringified List** of the secret names you want to extract.
66-
- To ensure your list of variables have the correct syntax, pass your array/list through a JSON.stringifier and pass the resulting string in here.
67-
- Note: We use `JSON.parse` to parse this string into a list since GitHub Actions does not currently support a list input
29+
- ##### githubToken:`string` (optional)
30+
31+
- GitHub access token with `repo` scop
6832

69-
- ##### GENERATE_ENV: `string` (optional)
70-
- The name of the `.env` file that you wish to generate. If your name contains a _`.`_, your provided name will become the file name of the `.env` file. If not, it will become the `{name} + .env`
33+
- ##### actor:`string` (optional)
34+
35+
- Provide the current actor of the workflow. By default it is the value of env.GITHUB_ACTO
7136

72-
For example:
37+
- ##### authorizedGroups:`string` (optional)
38+
39+
- Array of groups, i.e owners, admins, etc, managed as a Github Secret to allow only Repository Owners/Admins to change the value
7340

74-
- `mysecrets.env.local` as the `GENERATE_ENV` value, becomes `mysecrets.env.local`.
75-
- `mysecrets` as the `GENERATE_ENV` value, becomes `mysecrets.env`
76-
- ##### ALL_SECRETS: `boolean` (optional)
77-
- If you want to grab all the secrets on the hashicorp vault secrets app, set this to `true`. By default, this is `false`. If this is set, you do not need to set `SECRET_NAMES`
41+
- NOTE: This is **JSON Stringified List** that consists of any of the following values.
42+
`"owner" | "admin" | "member"`
7843

79-
### Using Action Output
44+
- To use this option, you MUST also supply a `githubToken` and a `githubOrg` in the action parameters
8045

81-
#### In a Github Action job
46+
- ##### authorizedActors:`string` (optional)
47+
48+
- Array of authorised actors, best managed as a GitHub Secret to allow only Repository Owners/Admins to change the values.
8249

83-
To use this action's output in subsequent workflow steps, ensure your `id` from the running action step, is the key to the subsquent step.
50+
- NOTE: This is **JSON Stringified List** of the Github usernames you want to allow.
8451

85-
##### Example:
52+
- ##### failSilently:`string` (optional)
53+
54+
Whether or not the GitHub action should exit with status code 1 or not
8655

87-
```yaml
88-
steps:
89-
- name: Hashicorp Vault Secrets
90-
id: hashicorp-vault-secrets
91-
uses: aasmal97/HashicorpVaultSecrets@v1.2.0
92-
with:
93-
CLIENT_ID: ${{ secrets.HASHICORP_CLIENT_ID }}
94-
CLIENT_SECRET: ${{ secrets.HASHICORP_CLIENT_SECRET }}
95-
ORGANIZATION_NAME: "example-org"
96-
PROJECT_NAME: "example-project"
97-
APP_NAME: "ci-cd-pipeline-app"
98-
SECRET_NAMES: '["EXAMPLE_ID"]'
99-
100-
- name: Example Step
101-
run: echo "The output value is ${{ steps.hashicorp-vault-secrets.outputs.EXAMPLE_ID }}"
102-
```
103-
104-
#### Using a generated .env file
56+
- ##### failureMessage:`string` (optional)
57+
58+
Message to display in the GitHub Action logs when authorised actor check fails
10559

106-
To use this, you must use the `GENERATE_ENV` input.
107-
108-
```yaml
109-
steps:
110-
- name: Hashicorp Vault Secrets
111-
uses: aasmal97/HashicorpVaultSecrets@v1.2.0
112-
with:
113-
CLIENT_ID: ${{ secrets.HASHICORP_CLIENT_ID }}
114-
CLIENT_SECRET: ${{ secrets.HASHICORP_CLIENT_SECRET }}
115-
ORGANIZATION_NAME: "example-org"
116-
PROJECT_NAME: "example-project"
117-
APP_NAME: "ci-cd-pipeline-app"
118-
SECRET_NAMES: '["EXAMPLE_ID"]'
119-
GENERATE_ENV: "example.env"
120-
121-
- name: Check if example.env exists
122-
shell: bash
123-
run: |
124-
if test -f /example.env; then
125-
echo "File exists."
126-
fi
127-
```
12860

129-
#### Load all secrets in Vault Secrets App
61+
## Limitations
13062

131-
```yaml
132-
steps:
133-
- name: Hashicorp Vault Secrets
134-
id: hashicorp-vault-secrets
135-
uses: aasmal97/HashicorpVaultSecrets@v1.2.0
136-
with:
137-
CLIENT_ID: ${{ secrets.HASHICORP_CLIENT_ID }}
138-
CLIENT_SECRET: ${{ secrets.HASHICORP_CLIENT_SECRET }}
139-
ORGANIZATION_NAME: "example-org"
140-
PROJECT_NAME: "example-project"
141-
APP_NAME: "ci-cd-pipeline-app"
142-
ALL_SECRETS: true
143-
144-
- name: Example Step
145-
run: echo "The output value is ${{ steps.hashicorp-vault-secrets.outputs.EXAMPLE_ID }}"
146-
```
63+
- To protect a branch, you need to write an additional step that if this fails, most recent push or merge request is reverted. This action does not handle this by default, because some users may want to only prevent certain ci/cd pipelines steps instead, and allow the branch to be merged.
14764

148-
## Limitations
65+
- The `authorizedGroups` and `authorizedActors` must be a string since list inputs are not supported by Github Actions. In the future, this may be changed, when Github supports list inputs natively.
14966

150-
- The service principal account must be configured at the **Organization Level**. This limitation is imposed by Hashicorp themselves, and until this changes, there can't be support for more granular access (i.e service principal for only a project).
151-
- The `SECRET_NAMES` must be a string since list inputs are not supported by Github Actions. In the future, this may be changed, when Github supports list inputs natively.
152-
- This action can only run in **ubuntu** environments. It is not supported in darwin or mac. This is due primarily to ubuntu being the most common environment for Github action runners, but it is also due to my lack of hardware and time. However, in the future, support can be added if it is seen as a good or necessary feature.
67+
- To use the `authorizedGroups` option, you MUST also supply a `githubToken` and a `githubOrg`. This is a because the organization that the repository belongs to is not immeaditely available in the runner. In addition, the github token supplied in the runner, will not have the organization-level permissions to grab an organization's members and determine their role. As a result, we need a githubToken to read this organization member data, and filter out the users by group, that will have permissions.
15368

15469
## Contributing
15570

@@ -164,16 +79,6 @@ To run the development environment, ensure the following are configured properly
16479
- [Docker](https://docs.docker.com/engine/install/) installed on your machine. It will provide the virtual environment needed to run a Github Action
16580
- [nektos/act](https://github.com/nektos/act) installed. This is the software that uses Docker to create a container, that resembles a Github Action Environment for testing
16681
- Have a package manager installed (i.e, npm, yarn, etc)
167-
- Create a Hashicorp Cloud Platform Account
168-
1. Go [here](https://portal.cloud.hashicorp.com/sign-in) and create an account
169-
2. Create a dummy organization
170-
3. Go to **Access Control IAM**, then go to **Service Principals** and create a dummy service principal account
171-
- **Save** the **_Client ID_** and **_Client Secret_** values in a `my.secrets` file in the following path `test/workflows/my.secrets`. `nektos/act` will use this to run the virtual github action.
172-
- Note: The `my.secrets` file follows the same form/syntax as a regular `.env` file.
173-
4. Create a dummy project in your organization
174-
5. Click on newly created dummy project, and go to **Vault Secrets**
175-
6. Go to **Applications** and create a dummy application
176-
7. Fill in the dummy application with dummy secrets
17782

17883
#### Running Dev Environment
17984

0 commit comments

Comments
 (0)