Skip to content

Commit

Permalink
docs(common): Improve CI/CD articles (#2148)
Browse files Browse the repository at this point in the history 
* initial commit

* docs(common): Revamp NuGet API Keys article

* add Docker information and polish

* Update deployment/ci-cd-build-server.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/nuget-keys.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/nuget-keys.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/nuget-keys.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/nuget-keys.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/nuget-keys.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/overview.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/overview.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update _contentTemplates/common/general-info.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update deployment/troubleshooting.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update installation/nuget.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update installation/nuget.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* final commit

---------

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>
  • Loading branch information
@dimodi @ikoevska
dimodi and ikoevska committed Jun 13, 2024
1 parent 780a0cd commit 4bd37a7
Show file tree
Hide file tree
Showing 18 changed files with 195 additions and 119 deletions.
2 changes: 1 addition & 1 deletion .spelling
View file
Original file line number Diff line number Diff line change
Expand Up @@ -248,7 +248,7 @@ NavigationManager
NestedFormItem
NoDataTemplate
NotificationModel
nuget.config
NuGet.Config
nuget.org
nuget.telerik.com
NullReferenceException
Expand Down
10 changes: 10 additions & 0 deletions _contentTemplates/common/general-info.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,3 +125,13 @@ If you set the `ShouldRender` field of the event arguments to `true`, the compon
| tb-window | [Window]({%slug window-overview%}) |
| tb-wizard | [Wizard]({%slug wizard-overview%}) |
#end

#status-telerik-com
## Telerik NuGet Feed Status

Visit [status.telerik.com](https://status.telerik.com) to check the status of the Telerik NuGet server. The top section shows manually logged incidents with possible updates or workaround suggestions. The [**System Metrics** section](https://status.telerik.com/#system-metrics) provides real-time automated diagnostics.
#end

#ci-cd-support
> All deployment articles in this documentation provide general guidance and fundamentals. Telerik does not provide technical support for setting up CI/CD environments or application publishing infrastructure.
#end
46 changes: 42 additions & 4 deletions deployment/ci-cd-build-server.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,16 @@ Sections in this article:
* [Basics](#basics)
* [Azure DevOps Pipelines](#azure-devops-pipelines)
* [GitHub Secrets](#github-secrets)
* [Docker](#docker)


## Basics

Often enough, you would want to set up Continuous Integration and/or Continuous Delivery (CI/CD) pipelines or builds for your project that uses the Telerik components. This is a valid scenario and the "one license per developer" license does not prevent you from doing so. The Telerik components are commercial software and as such can only be distributed through channels that are private and/or behind authentication.

There are a couple of common ways people implement CI/CD automated builds.

* You can [restore the Telerik NuGet packages]({%slug installation/nuget-keys%}) by downloading them from the Telerik NuGet server. You can achieve this by using the more secure token-based authentication with the Telerik NuGet server. If you prefer the basic authentication with a username and password, you can use your own credentials (or the credentials of the license holder, depending on how your licenses are set up) in the `nuget.config` of the build machine/pipeline. In this case, make sure that your credentials are encrypted when you add the Telerik feed source through the CLI. Alternatively, you can copy an encrypted version from your own local config if you have one and if plain text is an issue. See more on setting up the [Telerik NuGet package source]({%slug installation/nuget%}).
* You can [restore the Telerik NuGet packages]({%slug installation/nuget-keys%}) by downloading them from the Telerik NuGet server. You can achieve this by using the more secure token-based authentication with the Telerik NuGet server. If you prefer the basic authentication with a username and password, you can use your own credentials (or the credentials of the license holder, depending on how your licenses are set up) in the `NuGet.Config` of the build machine/pipeline. In this case, make sure that your credentials are encrypted when you add the Telerik feed source through the CLI. Alternatively, you can copy an encrypted version from your own local config if you have one and if plain text is an issue. See more on setting up the [Telerik NuGet package source]({%slug installation/nuget%}).

* Creating a local folder (for example, on a shared network drive or other suitable location accessible only by your builds and team) that holds the `.nupkg` files we provide (you can download them from your telerik.com account, or from your local installation - both [automated]({%slug installation/msi%}) and from the [zip archive]({%slug installation/zip%})).

Expand All @@ -44,7 +46,7 @@ When using Azure pipelines, we encourage you to review the following resources o
* Obtaining credentials - see the points above for either using your own credentials, or using a shared package source.

* Telerik feed not being found - the most common reason for a problem is that the path to the `nuget.config` file is wrong (it should, by default, be at the root level).
* Telerik feed not being found - the most common reason for a problem is that the path to the `NuGet.Config` file is wrong (it should, by default, be at the root level).

* An `index.json not found` error can occur from many root causes. If you have successfully authenticated, this error usually means that the feed wasn't able to be searched or connected to. A common reason is an incorrect feed URL, such as including a trailing slash - Correct: `https://nuget.telerik.com/v3/index.json` and Incorrect: `https://nuget.telerik.com/v3/index.json/`.

Expand All @@ -61,7 +63,7 @@ When using Azure pipelines, we encourage you to review the following resources o

## GitHub Secrets

In some cases, [GitHub Secrets](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) are used to store credentials that you would later have to consume from the `nuget.config` file in order to connect to the Telerik feed in your GitHub Actions workflows.
In some cases, [GitHub Secrets](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) are used to store credentials that you would later have to consume from the `NuGet.Config` file in order to connect to the Telerik feed in your GitHub Actions workflows.

A way to pass them along is to mark them as environment variables. You can find an example in the [DevOpsExamples repo by Lance McCarthy](https://github.com/LanceMcCarthy/DevOpsExamples). Here follow the two relevant extracts.

Expand All @@ -80,7 +82,7 @@ jobs:

>tip Even though you are copying secrets into Environment Variables on the runner, GitHub Actions will continue to treat the values as protected string and mask the values in all output.
Finally, you need a `nuget.config` file that lists the Telerik server in the `packageSources`, as well as an accompanying `packageSourceCredentials` that uses those named environment variables for the `Username` and `ClearTextPassword` keys.
Finally, you need a `NuGet.Config` file that lists the Telerik server in the `packageSources`, as well as an accompanying `packageSourceCredentials` that uses those named environment variables for the `Username` and `ClearTextPassword` keys.

>caption Example of Using Environment Variables in NuGet.config
Expand All @@ -101,6 +103,42 @@ Finally, you need a `nuget.config` file that lists the Telerik server in the `pa
>warning GitHub does not allow secrets to be used in workflows that have been [triggered by a pull request event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows). In such a case, the runner will not be able to authenticate with the Telerik NuGet server and the job will expectedly fail.

## Docker

When building or restoring Blazor apps in Docker, the crucial steps are:

1. Have a `NuGet.Config` file in the project or solution folder. The file can [define the Telerik NuGet feed]({%slug installation/nuget%}#edit-the-nugetconfig-file), but without the credentials (Telerik account or NuGet API key).
1. Copy the `NuGet.Config` file together with the `.csproj` file(s) to the Docker image.
1. [Add](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-add-source) or [update](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-update-source) the Telerik NuGet feed with the [stored Telerik NuGet credentials (secrets)]({%slug installation/nuget-keys%}). When specifying the `NuGet.Config` file location, note that file names are case-sensitive on Unix systems.
1. Restore or build the Blazor app.

The following code is the build portion of a sample `Dockerfile` that builds a .NET 8 Blazor Web App with two projects. The `dotnet restore` command is executed from the `src` folder of the Docker image (where the `NuGet.Config` is copied), so that the `NuGet.Config` file can be used to restore all projects in the solution.

```
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
# Copy the project files to restore in child folders of /src
COPY ["MyBlazorApp/MyBlazorApp/MyBlazorApp.csproj", "MyBlazorApp/MyBlazorApp/"]
COPY ["MyBlazorApp/MyBlazorApp.Client/MyBlazorApp.Client.csproj", "MyBlazorApp/MyBlazorApp.Client/"]
# Copy the NuGet.Config file without the Telerik credentials to /src
COPY ["NuGet.Config", "."]
# Update the Telerik NuGet source and add credentials from your secrets storage
RUN dotnet nuget update source "TelerikOnlineFeed" --username ... --password ... --configfile "./NuGet.Config" --store-password-in-clear-text
# Restore the NuGet packages for the Blazor app
RUN dotnet restore "./MyBlazorApp/MyBlazorApp/MyBlazorApp.csproj"
# Copy the whole Blazor app
COPY . .
# Build the app
WORKDIR "/src/MyBlazorApp/MyBlazorApp"
RUN dotnet build "./MyBlazorApp.csproj" -c Release -o /app/build
```


## Further Reading

Expand Down
110 changes: 50 additions & 60 deletions deployment/nuget-keys.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,115 +3,105 @@ title: Restoring NuGet Packages in CI
page_title: Restoring NuGet Packages in CI
description: Get started with Telerik UI for Blazor and use NuGet Keys to authenticate with the Telerik NuGet server and restore packages in your CI or desktop environment.
slug: installation/nuget-keys
position: 7
position: 10
---

# Restoring NuGet Packages in Your CI Workflow

This article provides an overview of the most popular ways for using token-based authentication to restore Telerik NuGet packages in your Continuous Integration (CI) workflow.
This article describes how to use token-based authentication for the Telerik NuGet feed. You will learn how to create and use NuGet API keys to restore Telerik NuGet packages in your Continuous Integration (CI) workflow.

The Telerik NuGet server allows you to authenticate by using two methods:
The [Telerik NuGet server]({%slug installation/nuget%}) provides two ways to authenticate:

* Basic authentication by providing your Telerik user name and password.
* Token-based authentication by providing a NuGet Key.
* Basic authentication with your Telerik username and password.
* Token-based authentication with a NuGet API key.

When you need to restore Telerik NuGet packages as part of your CI, using NuGet keys is the more secure way to authenticate. This method does not require you to provide your Telerik username and password anywhere in the CI workflow.
When you need to restore the [Telerik NuGet packages]({%slug getting-started/what-you-need%}#nuget-packages) as part of your CI, a NuGet API key is the more secure way to authenticate. This method does not require you to provide your Telerik credentials anywhere in the CI workflow. A NuGet Key has a limited scope and can be used only with the Telerik NuGet server. If any of your NuGet keys is compromised, you can quickly delete it and create a new one.

Unlike your Telerik credentials, a NuGet Key has a limited scope and can be used only with the Telerik NuGet server. If any of your NuGet keys is compromised, you can quickly delete it and create a new one.

## Generating NuGet Keys

1. Go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page in your Telerik account.
1. In your Telerik account, go to the [**Manage NuGet Keys**](https://www.telerik.com/account/downloads/nuget-keys) page.

![Manage NuGet Keys](../deployment/images/manage-nuget-keys.png)

1. To create a new key, click on the **Generate New Key** button.
1. Click **Generate New Key**.

1. Enter a name for the NuGet Key, and then select **Generate Key**.
1. Enter a name for the NuGet Key and click **Generate Key**.

1. To copy the key, select **Copy and Close**. Once you close the window, you can no longer copy the generated key. For security reasons, the **NuGet Keys** page displays only a portion of the key.
1. To copy the key, click **Copy and Close**. Once you close the popup dialog, you can no longer copy the generated key. For security reasons, the **NuGet Keys** page displays only a portion of the key.

![Copy Generated NuGet Key](../deployment/images/copy-nuget-key.png)

## Storing a NuGet Key

> Never check in a NuGet Key with your source code or leave it publicly visible in plain text, for example, as a raw key value in a `nuget.config` file. A NuGet Key is valuable as bad actors can use it to access the NuGet packages that are licensed under your account. A potential key abuse could lead to a review of the affected account.
## Storing NuGet Keys

To protect the NuGet Key, store it as a secret environment variable. The exact steps depend on your workflow:
>warning Never check in Telerik account credentials or a NuGet API key with your source code or leave them publicly visible in plain text (for example, in a `NuGet.Config` file). A NuGet key is valuable and bad actors can use it to access the NuGet packages that are licensed under your account. A key abuse can lead to a review of the affected Telerik account.
* In GitHub Actions, save the key as a GitHub Actions Secret. Go to **Settings** > **Security** > **Secrets** > **Actions** > **Add new secret**.
To protect the NuGet Key, store it as a secret environment variable. The exact store steps depend on your workflow and environment:

* In Azure DevOps Classic, save the key as a secret pipeline variable. Go to the **Variables** tab and then select **Pipeline variables**.

* In Azure DevOps YAML pipelines, save the key as a secret variable as well. Click the YAML editor's **Variables** button and complete the **New variable** form.

If you use Azure DevOps Service connection instead of secret environment variables, enter `api-key` in the username filed and the NuGet Key as the password in the **New NuGet service connection** form editor.
* In GitHub Actions, save the key as a [GitHub Actions Secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
* In Azure DevOps, save the key as a [secret Azure DevOps pipeline variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables). If you use an Azure DevOps Service connection instead of secret environment variables, enter `api-key` in the username field and the NuGet key as the password in the **New NuGet service connection** form editor.
* In Docker images, save the key as a [Docker secret](https://docs.docker.com/tags/secrets/).

For more details on storing and protecting your NuGet Key, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.

## Using a NuGet Key
The examples below assume that the secret environment variable name is `TELERIK_NUGET_KEY`.

There are two popular ways to use the Telerik NuGet server in a build:

* [Using a nuget.config file with your projects](#using-a-nugetconfig-file-with-your-projects)
## Using NuGet Keys

There are two common ways to use a [stored NuGet key](#storing-nuget-keys) with the Telerik NuGet server during a build:

* [Using a NuGet.Config file](#using-a-nugetconfig-file)
* [Using only CLI commands](#using-only-cli-commands)

For more information on how to use NuGet keys in a build, check the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.

### Using a nuget.config File with Your Projects

1. In your `nuget.config` file, set the `Username` value to `api-key` and the `ClearTextPassword` value to an environment variable name:

```xml
<configuration>
<packageSources>
<clear/>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="MyTelerikFeed" value="https://nuget.telerik.com/v3/index.json" protocolVersion="3"/>
</packageSources>
<packageSourceCredentials>
<MyTelerikFeed>
<add key="Username" value="api-key" />
<add key="ClearTextPassword" value="%MY_API_KEY%" />
</MyTelerikFeed>
</packageSourceCredentials>
...
</configuration>
```
### Using a NuGet.Config File

1. Set the `MY_API_KEY` environment variable by using the value of your pipeline/workflow secret.
In your `NuGet.Config` file, set the `Username` value to `api-key` and the `ClearTextPassword` value to an environment variable name:

The exact steps to set the `MY_API_KEY` environment variable depend on your workflow. For more details, refer to the [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys) blog post by Lance McCarthy.
<div class="skip-repl"></div>

### Using Only CLI Commands
```xml
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
<add key="TelerikOnlineFeed" value="https://nuget.telerik.com/v3/index.json" protocolVersion="3" />
</packageSources>
<packageSourceCredentials>
<TelerikOnlineFeed>
<add key="Username" value="api-key" />
<add key="ClearTextPassword" value="%TELERIK_NUGET_KEY%" />
</TelerikOnlineFeed>
</packageSourceCredentials>
</configuration>
```

You can use the CLI `add source` (or `update source`) command to set the credentials of a package source. This CLI approach is applicable if your CI system doesn't support default environment variable secrets or if you do not use a custom `nuget.config`.
### Using .NET CLI Commands

You can use the .NET CLI `add source` or `update source` commands to set the credentials of a package source. This CLI approach is applicable if your CI system doesn't support [environment variable secrets](#storing-nuget-keys) or if you do not [use a custom `NuGet.Config`](#using-a-nugetconfig-file).

* To set the credentials in Azure DevOps:

```
dotnet nuget add source 'MyTelerikFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '$(TELERIK_NUGET_KEY)' --configfile './nuget.config' --store-password-in-clear-text
dotnet nuget add source 'TelerikOnlineFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '$(TELERIK_NUGET_KEY)' --configfile './NuGet.Config' --store-password-in-clear-text
```

* To set the credentials in GitHub Actions:

```
dotnet nuget add source 'MyTelerikFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '${{ secrets.TELERIK_NUGET_KEY }}' --configfile './nuget.config' --store-password-in-clear-text
dotnet nuget add source 'TelerikOnlineFeed' --source 'https://nuget.telerik.com/v3/index.json' --username 'api-key' --password '${{ secrets.TELERIK_NUGET_KEY }}' --configfile './NuGet.Config' --store-password-in-clear-text
```

## Additional Resources

If you just start using the Telerik NuGet server in your CI or inter-department workflows, check the two blog posts below. You will learn about the various use cases and find practical implementation details.

* [Azure DevOps and Telerik NuGet Packages](https://www.telerik.com/blogs/azure-devops-and-telerik-nuget-packages)

* [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys)

When restoring NuGet packages through the CLI, [use `dotnet restore` rather than `nuget restore` to avoid compatibility errors]({%slug common-kb-package-telerik-pivot-not-compatible-with-netframework%}).
> When restoring NuGet packages through the CLI, [use `dotnet restore` rather than `nuget restore` to avoid compatibility errors]({%slug common-kb-package-telerik-pivot-not-compatible-with-netframework%}).

## See Also

* [Telerik NuGet Feed]({% slug installation/nuget %})
* [CI, CD, Build Server Setup]({% slug deployment-ci-cd-build-pc %})
* [Telerik NuGet Feed]({%slug installation/nuget%})
* [CI, CD, Build Server Setup]({%slug deployment-ci-cd-build-pc%})
* [Azure DevOps and Telerik NuGet Packages](https://www.telerik.com/blogs/azure-devops-and-telerik-nuget-packages)
* [Announcing NuGet Keys](https://www.telerik.com/blogs/announcing-nuget-keys)
Loading

0 comments on commit 4bd37a7

Please sign in to comment.