Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Releases - DevOps for ASP.NET Core Developers eBook V1.1 #23784

Merged
merged 44 commits into from
Apr 20, 2021
Merged
Show file tree
Hide file tree
Changes from 39 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
7a8703d
Included DevOps with ASP.NET Core and Azure eBook (#23098)
Mar 3, 2021
faec7b2
Included toc yaml for devops ebook
sughosneo Mar 10, 2021
751a89f
Devops ebook (#23137)
colindembovsky Mar 16, 2021
e8767d3
Adding GitHub Actions .NET Deployment Article (#23332)
colindembovsky Mar 19, 2021
092ba4b
CodeQL Article (#23392)
colindembovsky Mar 22, 2021
2658874
DevOps eBook: GitHub Actions vs Azure Pipelines (#23441)
colindembovsky Mar 23, 2021
2a6dc59
Devops ebook: Actions index (#23462)
colindembovsky Mar 24, 2021
bd450fb
Edit pass on GitHub Actions eBook content
scottaddie Mar 25, 2021
2a3e658
Adjust the DevOps for ASP.NET Core Developers eBook TOC (#23552)
IEvangelist Mar 30, 2021
f0c6872
Fix for devops-ebook (#23568)
Mar 31, 2021
7053982
Updated index page (#23771)
Apr 13, 2021
389cc3a
Merge branch 'main' into devops-ebook
sughosneo Apr 14, 2021
85a1152
Update docs/architecture/devops-for-aspnet-developers/monitoring.md
Apr 14, 2021
4813c7f
Update docs/architecture/devops-for-aspnet-developers/monitoring.md
Apr 14, 2021
e274f2e
Update docs/architecture/devops-for-aspnet-developers/monitoring.md
Apr 14, 2021
0d8d17c
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
88bebea
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
771532c
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
3bb1278
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
4097fe8
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
0703546
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
81149c4
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
8a1d313
Update docs/architecture/devops-for-aspnet-developers/actions-build.md
Apr 15, 2021
b2f497a
Update docs/architecture/devops-for-aspnet-developers/actions-codeql.md
Apr 15, 2021
2ef104f
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 15, 2021
9911a11
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 15, 2021
e454a0a
Update docs/architecture/devops-for-aspnet-developers/actions-vs-pipe…
Apr 15, 2021
383e9f4
Update docs/architecture/devops-for-aspnet-developers/actions-vs-pipe…
Apr 15, 2021
be15cc0
Update docs/architecture/devops-for-aspnet-developers/actions-vs-pipe…
Apr 15, 2021
278401b
Included review suggestions
sughosneo Apr 15, 2021
53ba0fb
Fixed lint errors
sughosneo Apr 15, 2021
11cb504
Included further suggestions
sughosneo Apr 15, 2021
64b258b
Removed unncessary codefence
sughosneo Apr 15, 2021
631a015
Apply suggestions from code review
Apr 16, 2021
09b9e13
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 16, 2021
de2aac7
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 16, 2021
7038551
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 16, 2021
1723cb3
Update docs/architecture/devops-for-aspnet-developers/actions-deploy.md
Apr 16, 2021
0be7e84
Changed default branch from master to main
sughosneo Apr 16, 2021
34dc4ee
Updated cicd content
sughosneo Apr 20, 2021
b6731c8
Fixed build related warning
sughosneo Apr 20, 2021
1e6db25
Fixed indentation
sughosneo Apr 20, 2021
33a100a
Apply suggestions from code review
IEvangelist Apr 20, 2021
42e87a2
Apply suggestions from code review
IEvangelist Apr 20, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 205 additions & 0 deletions docs/architecture/devops-for-aspnet-developers/actions-build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
---
title: DevOps with .NET and GitHub Actions - Build a .NET Web App
description: Start your journey of DevOps with .NET and GitHub Actions by building a .NET web app
author: colindembovsky
ms.date: 03/04/2021
---
# Build a .NET web app using GitHub Actions

[GitHub Actions](https://github.com/features/actions) allow you to automate workflows in response to events that are triggered in GitHub. A common workflow is Continuous Integration (CI), but Actions can automate other processes. For example, sending welcome emails when people join a repository.

To explore moving code to the cloud, you'll build a GitHub Actions workflow file. The workflow file will be used for the Simple Feed Reader app you've already deployed to Azure App Service.

In this article, you will:
> [!div class="checklist"]
>
> * Learn the basic structure of a GitHub Action workflow YAML file.
> * Use a template to create a basic build workflow that builds the .NET app and executes unit tests.
> * Publish the compiled app so that it's ready for deployment.

## Workflow structure

Workflows are defined in YAML files, and contain several common nodes:

- a `name`
- a trigger, defined by an `on` section
- one or more `job` sections composed of one or more `steps`
- optional attributes such as `environment` variables

Jobs are run on *runners*. You can use *hosted runners*, which are spun up by GitHub during the workflow and then thrown away. Hosted runners are great because you don't have to maintain your own build infrastructure. For workflows that require a specific build environment, or for running workflows on a private network, you can also use *private* runners. To create a private runner, install the runner on any machine that supports .NET.

Each `job` will specify what runner GitHub should use to execute the `steps`. You can also specify dependencies between jobs using the `needs` attribute. Deployment jobs can also specify an `environment` to target.

The `steps` node can be as easy as inline commands, or they can be actions. Most CI workflows will have a combination of `run` steps (for executing scripts) and actions. Individual actions are pulled into the workflow by referencing the GitHub Action repository (and optionally a tag or commit hash for specific versions) and specifying any parameters using the `with` keyword.

> [!TIP]
> For more information, see [GitHub Actions YAML syntax](https://docs.github.com/actions/reference/workflow-syntax-for-github-actions).

## Create a basic build workflow

A primary principle of effective DevOps is to "build once, and deploy many times". You'll start by creating a workflow to build a basic .NET app. In the next step, you'll publish the output to prepare for deployment.

1. Navigate to your GitHub repository and select the **Actions** tab.
1. GitHub detects that there's .NET code in the repository and suggests a .NET workflow template. Select **Set up this workflow** to create a new YAML workflow file:

![Creating a new workflow](./media/actions/build/new-action.jpg)

**Figure 1**: Creating a new workflow.
sughosneo marked this conversation as resolved.
Show resolved Hide resolved

1. Commit the file onto the `main` branch. Since you've defined a trigger condition for *commits to main*, this commit should trigger the workflow to run.

![Commit the YAML file](./media/actions/build/commit-workflow.jpg)

**Figure 2**: Commit the YAML file.

1. Select the **Actions** tab again. You should see a running workflow. Once the workflow has completed, you should see a successful run.

![Successful build view](./media/actions/build/build-action-success.jpg)

**Figure 3**: Successful build view.

1. Opening the logs, you can see that the .NET build succeeded and the tests ran and passed.

![Checking the logs](./media/actions/build/build-action-success-logs.jpg)

**Figure 4**: Checking the logs.

> [!NOTE]
> If any of the tests fail, the workflow will fail.

## Dissect the workflow file

Let's examine the workflow YAML file you have so far:

```yml
name: .NET

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build:

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2
- name: Setup .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: 5.0.x
- name: Restore dependencies
run: dotnet restore
- name: Build
run: dotnet build --no-restore
- name: Test
run: dotnet test --no-build --verbosity normal
```

Notice the following things:

1. There's a `name` that names the workflow.
1. The `on` object specifies when this workflow should run. This workflow has two events that trigger it: `push` to `main` and `pull_request` to `main`. Each time someone commits to `main` or creates a pull request (PR) to `main`, this workflow will execute.
1. There's a single `job` called `build`. This build should run on a hosted agent. `ubuntu_latest` specifies the most recent Ubuntu hosted agent.
1. There are five steps:
1. `actions/checkout@v2` is an action that checks out the code in the repository onto the runner.
1. `actions/setup-dotnet@v1` is an action that sets up the .NET CLI. This step also specifies a `name` attribute for the logs and the `dotnet-version` parameter within the `with` object.
1. Three `run` steps that execute `dotnet restore`, `dotnet build`, and `dotnet test`. `name` attributes are also specified for these `run` steps to make the logs look pretty.

## Publish the output

Now that you've successfully built and tested the code, add steps that publish the output so you can deploy the web app.

1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit it.

![Edit the YAML file](./media/actions/build/click-edit.jpg)

**Figure 5**: Edit the YAML file.

1. Add the following `Publish` step below the `Test` step. The step runs the `dotnet publish` command to publish the web app:

```yml
- name: Test
run: dotnet test --no-build --verbosity normal # <-- this is the current bottom line

- name: Publish
run: dotnet publish SimpleFeedReader/SimpleFeedReader.csproj -c Release -o website
```

1. This publishes the web app to a folder on the hosted agent. Now you'll want to *upload* the site as a build artifact that can be deployed to Azure. To complete this activity, you'll use an existing action.
1. On the list of actions in the **Actions Helper** pane on the right, search for `artifact`. Select on the `Upload a Build Artifact (By actions)` action.

![Accessing the Actions helper](./media/actions/build/search-upload-artifact.jpg)

**Figure 6**: Accessing the snippet helper.

1. Edit the version to `v2.2.2` to display a sample snippet. Select the clipboard icon to copy the snippet and paste it into the workflow below the publish step.

![Copying a snippet](./media/actions/build/copy-snippet.jpg)

**Figure 7**: Copying a snippet.

1. Edit the YAML for this step to look as follows:

```yml
- name: Upload a Build Artifact
uses: actions/upload-artifact@v2.2.2
with:
name: website
path: SimpleFeedReader/website/**
if-no-files-found: error
```

1. Commit the file.
1. Once the workflow completes, you'll see the artifact from the **Home** tab:

![Viewing artifacts in the summary page](./media/actions/build/view-uploaded-artifact.jpg)

**Figure 8**: Viewing artifacts in the summary page.

### Final workflow file

The final workflow file should look something like this:

```yml
name: .NET

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build:

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2
- name: Setup .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: 5.0.x
- name: Restore dependencies
run: dotnet restore
- name: Build
run: dotnet build --no-restore
- name: Test
run: dotnet test --no-build --verbosity normal
- name: Publish
run: dotnet publish SimpleFeedReader/SimpleFeedReader.csproj -c Release -o website
- name: Upload a Build Artifact
uses: actions/upload-artifact@v2.2.2
with:
name: website
path: SimpleFeedReader/website/**
if-no-files-found: error
```

>[!div class="step-by-step"]
>[Previous](actions-vs-pipelines.md)
>[Next](actions-deploy.md)
192 changes: 192 additions & 0 deletions docs/architecture/devops-for-aspnet-developers/actions-codeql.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
---
title: DevOps with .NET and GitHub Actions - Secure code with CodeQL
description: Add security scanning to your .NET code with GitHub Actions and CodeQL
author: colindembovsky
ms.date: 03/04/2021
---

# Secure .NET Code with CodeQL and GitHub Actions

[CodeQL](https://codeql.github.com/docs/codeql-overview/about-codeql/) is a static code analysis engine that can automate security and quality checks. With CodeQL, you can perform *variant analysis*, which uses known vulnerabilities as seeds to find similar issues. CodeQL is part of [GitHub Advanced Security](https://docs.github.com/github/getting-started-with-github/about-github-advanced-security) that includes:

> [!div class="checklist"]
>
> * Code scanning&mdash;find potential security vulnerabilities in your code.
> * Secret scanning&mdash;detect secrets and tokens that are committed.
> * Dependency scanning&mdash;detect vulnerabilities in packages that you consume.

CodeQL [supports some of the most popular programming languages and compilers](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/):

- C/C++
- Java
- C#
- Python
- Go
- JavaScript
- TypeScript

CodeQL is a powerful language and security professionals can create custom queries using CodeQL. However, teams can benefit immensely from the large open-source collection of queries that the security community has created without having to write any custom CodeQL.

In this article, you'll set up a GitHub workflow that will scan code in your repository using CodeQL. You will:

> [!div class="checklist"]
>
> * Create a code scanning action.
> * Edit the workflow file to include custom scan settings.
> * See scanning results.

> [!NOTE]
> To see security alerts for your repository, you must be a repository owner.

## Create the code scanning workflow

You can use a starter workflow for code scanning by navigating to the **Security** tab of your repository.

1. Navigate to your GitHub repository and select the **Security** > **Code Scanning Alerts**. The top recommended workflow should be CodeQL Analysis. Select **Set up this workflow**.

![Create a new code scanning workflow](./media/actions/codeql/setup-workflow.jpg)

**Figure 1:** Create a new code scanning workflow.

1. A new workflow file is created in your *.github/workflows* folder.
1. Select **Start Commit** on the upper right to save the default workflow. You can commit to the `main` branch.

![Commit the file](./media/actions/codeql/start-commit.jpg)

**Figure 2:** Commit the file.

1. Select the **Actions** tab. In the left-hand tree, you'll see a **CodeQL** node. Select this node to filter for CodeQL workflow runs.

![View the CodeQL workflow runs](./media/actions/codeql/codeql-run.jpg)

**Figure 3:** View the CodeQL workflow runs.

Take a look at the workflow file while it runs. If you remove the comments from the file, you'll see the following YAML:

```yml
name: "CodeQL"

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
schedule:
- cron: '40 14 * * 6'

jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest

strategy:
fail-fast: false
matrix:
language: [ 'csharp' ]

steps:
- name: Checkout repository
uses: actions/checkout@v2

- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}

- name: Autobuild
uses: github/codeql-action/autobuild@v1

- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1
```

Notice the following things:

1. The workflow `name` is `CodeQL`.
1. This workflow triggers on `push` and `pull_request` events to the `main` branch. There's also a `cron` trigger. The `cron` trigger lets you define a schedule for triggering this workflow and is randomly generated for you. In this case, this workflow will run at 14:40 UTC every Saturday.

> [!TIP]
> If you edit the workflow file and hover over the cron expression, a tooltip will show you the English text for the cron expression.

1. There's a single job called `analyze` that runs on the `ubuntu-latest` hosted agent.
1. This workflow defines a `strategy` with a `matrix` on the array of `language`. In this case, there's only `csharp`. If the repository contained other languages, you could add them to this array. This causes the job to "fan out" and create an instance per value of the matrix.
1. There are four steps, starting with `checkout`.
1. The second step initializes the CodeQL scanner for the `language` this job is going to scan. CodeQL intercepts calls to the compiler to build a database of the code while the code is being built.
1. The `Autobuild` step will attempt to automatically build the source code using common conventions. If this step fails, you can replace it with your own custom build steps.
1. After building, the CodeQL analysis is performed, where suites of queries are run against the code database.
1. The run should complete successfully. However, there appear to be no issues.

![No results to the initial scan](./media/actions/codeql/no-results.jpg)

**Figure 4:** No results to the initial scan.

## Customize CodeQL settings

The CodeQL scan isn't reporting any security issues. That's expected with this basic sample. CodeQL can also scan for *quality* issues. The current workflow is using the default `security-extended` suite. You can add quality scanning in by adding a configuration file to customize the scanning suites. In this step, you'll configure CodeQL to use the `security-and-quality` suites.

> [!INFORMATION]
> For other CodeQL configuration options, see [Configuring CodeQL code scanning in your CI system](https://docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-codeql-code-scanning-in-your-ci-system).

1. Navigate to the *.github* folder in the **Code** tab and select **Add File**:

![Create a new file](./media/actions/codeql/create-new-file.jpg)

**Figure 5:** Create a new file.

1. Enter *codeql/codeql-config.yml* as the name. This creates the file in a folder. Paste in the following code:

```yml
name: "Security and Quality"

queries:
- uses: security-and-quality
```

![Create the CodeQL config file](./media/actions/codeql/codeql-config.jpg)

**Figure 6:** Create the CodeQL configuration file.

1. Select **Commit to main** at bottom of the editor to commit the file.
1. Edit the CodeQL workflow to use the new configuration file. Navigate to *.github/workflows/codeql-analysis.yml* and select the pencil icon. Add a new property to the `with` section as shown below:

```yml
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}
config-file: ./.github/codeql/codeql-config.yml # <-- add this line
```

1. Select **Start Commit** and commit to the `main` branch.

## Review the security alerts

> [!IMPORTANT]
> You must be a repository owner to view security alerts.
>
> This sample repository is small. As such, it doesn't contain any major security or quality issues. However, "real world" repositories will likely have some issues.

When the last CodeQL workflow run completes, you should see two issues in the **Security** tab:

![View security alerts](./media/actions/codeql/security-alerts.jpg)

**Figure 7:** View security alerts.

1. Select the first alert to open it.
1. In this case, the alert is for a generated file that isn't committed to the repository. For that reason, the preview is unavailable.
1. Notice the tags that are applied. These tags can be used for filtering issues.
1. Select **Show more** under the rule information to show help and recommendations.

![Open an alert](./media/actions/codeql/alert.jpg)

**Figure 8:** Open an alert.

1. Selecting **Dismiss** will open options for dismissing this issue:

![Dismiss an alert](./media/actions/codeql/dismiss.jpg)

**Figure 9:** Dismiss an alert.

>[!div class="step-by-step"]
>[Previous](actions-deploy.md)
>[Next](monitoring.md)
Loading