Skip to content

Latest commit

 

History

History
175 lines (120 loc) · 8.41 KB

ReadMe.md

File metadata and controls

175 lines (120 loc) · 8.41 KB

Finish setting up your repo

Important

Congratulations on initializing your repository! 🎉

🚧 You are not quite done yet though. 🚧

Complete the following steps to finish setting up your repository.

📄 Template setup instructions

Steps 1 and 2 were already performed to get this far.

➕ Step 3: Add your module (if applicable)

If you already have the module, manifest, and tests written, replace the following files with your module's files:

Otherwise, use these files as a starting point for your new module.

Smoke tests

When you change the module and tests, you will also need to update the Smoke tests, otherwise they may fail the CI/CD workflow. See the Contributing docs for more information on smoke tests.

🚀 Step 4: Update your CI/CD workflows

🔑 Create a PowerShell Gallery API Key

In order to publish the module to the gallery, you need to get an API key. If you already have an API key that you want to use, you can skip to the next step.

Caution

It is considered best practice to use a different API key for each module you publish. It reduces the impact scope if one of the API keys becomes compromised.

If you will be publishing the module to a custom PowerShell Gallery feed, you will need to get an API key for that feed. Otherwise, follow the steps below.

Click to view steps to create a new API Key for the PowerShell Gallery...
  1. Navigate to https://www.powershellgallery.com/account/apikeys, and login if necessary.
  2. Click Create to create a new API key for this module.
  3. For the Key Name it is a good idea to include the name of your module. e.g. __NewModuleName__ module CI/CD pipeline
  4. Ensure the Push new packages and package versions scope is selected.
  5. For the Glob Pattern enter the name of your module: __NewModuleName__
  6. Click the Create button to create the API key.
  7. Click the Copy button on the new API key to copy it to your clipboard, as you will need it for the next section.

You may want to leave this page open in your browser until you have the API key saved in your repository secrets in the next section.

▶ GitHub Actions and Azure DevOps Pipelines setup instructions

Building and publishing the PowerShell module using GitHub Actions and Azure DevOps Pipelines are both supported. Follow the instructions for the CI/CD platform you plan to use.

Click to see GitHub setup instructions...

If using GitHub Actions for your CI/CD workflows, perform the following steps to setup your API key as a repository secret:

  1. Navigate to your GitHub repository in your browser.
  2. Go to the Settings tab for your repository.
  3. In the left-hand menu, in the Security section, click on Secrets and variables and select Actions.
  4. In the Secrets tab click the New repository secret button.
  5. Set the Secret value to the API key value that you copied in the previous section.
  6. Set the Name to: POWERSHELL_GALLERY_API_KEY
  7. Click the Add secret button to save the repository secret.

If you do not provide a valid API key, you will get an error like the following in the Publish prerelease PowerShell module step of the deployment workflow:

Failed to publish module '<module name>': 'dotnet cli failed to nuget push Pushing <module name>.nupkg to '<url>'...
PUT <url> Forbidden
error: Response status code does not indicate success: 403 (The specified API key is invalid, has expired, or does not have permission to access the specified package.).

Next we want to create an Environment so that stable module versions require manual approval before being published to the gallery:

  1. You should still be in the Settings section of your repository.
  2. In the left-hand menu, in the Code and automation section, click on Environments.
  3. Click the New environment button.
  4. Set the Name to (all lowercase): production
  5. Click the Configure environment button.
  6. Check the Required reviewers checkbox and add the usernames of the people allowed to approve new stable version deployments. e.g. your GitHub username.
  7. Click the Save protection rules button.

If your GitHub account does not meet the requirements to use Environments, the Environments section or Required reviewers options may not be available. Deployments will still work, but they will not pause for manual approval and will automatically deploy the stable version directly after the prerelease version is published. You will instead need to add the Manual Workflow Approval action to the deployment workflow to block deployments until they are approved.

Finally, we will need to grant GitHub Actions permission to add git tags to the repository so it can keep track of the version number:

  1. You should still be in the Settings section of your repository.
  2. In the left-hand menu, in the Code and automation section, click on Actions and select General.
  3. Scroll down to Workflow permissions and ensure Read and write permissions is selected.
  4. Click the Save button for the Workflow permissions.

If you do not do this you will get the following error in the Set the new version tag step of the deployment workflow:

fatal: unable to access 'https://github.com/<Author>/<Repo>/': The requested URL returned error: 403
Click to see Azure DevOps setup instructions...

Coming soon.

✔ Step 5: Review and update boilerplate repo files

The following boilerplate git repository files should be reviewed and updated or removed as needed.

  • NewModuleName.psd1: Update the module manifest with your module's information, such as the Description and have the ProjectUri link to this repository, etc.
    • If using the default generated manifest, search for "TODO" to find the properties that are recommended to update.
  • Changelog: If you don't plan to track a changelog, remove this file and it's reference from the ReadMe.
  • License: Update to match your module's license, and ensure it uses the correct name and year in the copyright.
  • Contributing: Update to match your module's contributing guidelines, or remove it.
  • bug_report, feature_request, pull_request_template: Update these GitHub templates as needed to meet your requirements, or remove them.
  • Build and deployment workflows: The workflows include extra steps that you may not want, such as spell check, code coverage, etc. Review the workflows and remove any steps that you don't want to include in your CI/CD pipeline.
  • ReadMe: Update this file with your module's information. Some example template content is provided below; fill it out, or remove it and write your own.

Important

If you've made it this far, your repository is now ready for use! 🎉

You may delete this message and all of the file's content above it and commit any changes you've made.

NewModuleName PowerShell Module

💬 Description

A short description of what this project does. Include a link to the module in the gallery.

❓ Why this exists

A short description of why this project exists. What use-case is it meant to solve?

✨ Features

List the features of this project:

  • Feature 1
  • Feature 2

🚀 Quick start

A quick guide on how to get started with this module, including installation and usage:

  • A link to the module in the PowerShell Gallery.
  • Code examples of installing and and using the module.
  • Links to wiki or other documentation.

➕ How to contribute

Issues and Pull Requests are welcome. See the Contributing page for more details.

📃 Changelog

See what's changed in the application over time by viewing the changelog.