Skip to content

Commit b624b4d

Browse files
committed
docs: Add GitHub setup instructions to ReadMe
1 parent f7b874a commit b624b4d

File tree

1 file changed

+42
-1
lines changed
  • src/Template.PowerShell.ScriptModule/TemplateRepoFiles

1 file changed

+42
-1
lines changed

src/Template.PowerShell.ScriptModule/TemplateRepoFiles/ReadMe.md

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,50 @@ Otherwise, use these files as a starting point for your new module.
2424
This template includes CI/CD workflows for building and publishing the PowerShell module using both GitHub Actions and Azure DevOps Pipelines.
2525
Follow the instructions for the CI/CD system you plan to use.
2626

27+
#### Create a PowerShell Gallery API Key
28+
29+
In order to publish the module to the gallery, you need to get an API key.
30+
If you already have an API key that you want to use, you can skip to the next step.
31+
32+
> [!TIP]
33+
> It is considered best practice to use a separate API key for each module you publish.
34+
> It reduces the impact scope if one of the API keys becomes compromised.
35+
36+
To create a new API Key for the PowerShell Gallery:
37+
38+
1. Navigate to <https://www.powershellgallery.com/account/apikeys>, and login if necessary.
39+
1. Click `Create` to create a new API key for this module.
40+
1. For the `Key Name` it is a good idea to include the name of your module.
41+
e.g. `__NewModuleName__ module CI/CD pipeline`
42+
1. Ensure the `Push new packages and package versions` scope is selected.
43+
1. For the `Glob Pattern` enter the name of your module: `__NewModuleName__`
44+
1. Click the `Create` button to create the API key.
45+
1. Click the `Copy` button on the new API key to copy it to your clipboard, as you will need it for the next step.
46+
2747
#### GitHub Actions
2848

29-
If using GitHub Actions for your CI/CD workflows, perform the following steps:
49+
If using GitHub Actions for your CI/CD workflows, perform the following steps to setup your API key as a repository secret:
50+
51+
1. Navigate to your GitHub repository in your browser.
52+
1. Go to the `Settings` tab for your repository.
53+
1. In the left-hand menu, in the `Security` section, click on `Secrets and variables` and select `Actions`.
54+
1. In the `Secrets` tab click the `New repository secret` button.
55+
1. Set the `Name` to: `POWERSHELL_GALLERY_API_KEY`
56+
1. Set the `Secret` to the API key value that you copied in the previous step.
57+
58+
Next we want to create an Environment so that stable module versions require manual approval before being published to the gallery:
59+
60+
1. In the left-hand menu, in the `Environments` section, click on `Environments`.
61+
1. Click the `New environment` button.
62+
1. Set the `Name` to: `production`
63+
1. Click the `Configure environment` button.
64+
1. Check the `Required reviewers` checkbox and add the appropriate reviewers.
65+
1. Click the `Save protection rules` button.
66+
67+
If your account does not meet [the requirements to use `Environments`](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment), the `Environments` section will not be available.
68+
You will instead need to
69+
70+
TODO FINISH THESE INSTRUCTIONS.
3071

3172
#### Azure DevOps Pipelines
3273

0 commit comments

Comments
 (0)