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

docs/architecture/devops-for-aspnet-developers/actions-build.md

@@ -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.
+
+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)

docs/architecture/devops-for-aspnet-developers/actions-codeql.md

@@ -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—find potential security vulnerabilities in your code.
+> * Secret scanning—detect secrets and tokens that are committed.
+> * Dependency scanning—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)