GitHub Actions Workshop

Thank you very much for participating in the GitHub Actions hands-on workshop. GitHub Actions is a powerful automation tool, and I look forward to you learning the basics and experiencing it firsthand through this hands-on session.

The following are the necessary steps before starting the hands-on workshop.

Joining the Organization

Confirm the Invitation
First, please confirm that you have received an invitation email from GitHub. This email prompts you to join a specific GitHub organization that will be used in the hands-on workshop.
Respond to the Invitation
Click on the invitation link in the email. Clicking the link will open the GitHub login page. Log in here with your own GitHub account. After logging in, a screen will be displayed to join the invited organization. Follow the instructions to complete the joining process.
Join the Organization
This will give you access to the organization's repositories and projects.

The next step in the GitHub Actions hands-on workshop is to create your own repository. This process will help you understand the basic functions of GitHub. The following explains the detailed steps for creating a repository.

Creating a Repository

Access the Repository Creation Screen
First, access the GitHub dashboard and click the "New repository" button to proceed to the screen for creating a new repository.
Specify Repository Settings
- Select Owner: When creating a repository, make sure the correct owner is selected. In this case, select the invited organization as the owner.
- Specify Repository Name: Set a unique repository name that includes your username.
- Privacy Settings: Let's set the repository to private. This will limit access to the repository to invited users.
- Initialize Repository: This time, we will create the repository without initializing it. This will create the repository in an empty state.
Confirm the Repository
Once the repository is created, confirm that fact. Since we did not initialize it, GitHub displays options prompting you to create new files. From this screen, you can check the repository settings and add new files.

Once your new repository is ready, let's create index.html as the first file. This file will serve as the base for the web page published on GitHub Pages. You can understand the basic structure of HTML and create your own unique page. The steps are shown below.

Creating the `index.html` File

Create a New File
First, click the "Add file" button and select "Create new file" to proceed to the screen for creating a new file.
Set the File Name
Enter "index.html" for the file name. This will allow GitHub Pages to recognize this file as the home page of the website.
Enter HTML Code
Edit the file content by referring to the sample HTML code below or adding your own code as desired. This example includes a simple greeting and a link to GitHub.
```
<html>
  <head>
    <title>Welcome to my page</title>
  </head>
  <body>
    <h1>Hello! I'm [Your Name]</h1>
  </body>
</html>
```
Enter Commit Message
After finishing the editing, click "Commit changes" to save the changes. The commit message is important for describing the changes made. Enter a message that clearly communicates the changes.
Confirm the File
After saving, the created index.html file will be displayed within the repository. Now the target for publishing on GitHub Pages is ready.

GitHub Actions is a powerful tool for creating automated workflows. In this step, we will create a workflow to host the HTML file on GitHub Pages. By using GitHub Actions, the web page will be automatically updated whenever there are changes to the code. The procedure is explained below.

Setting Up GitHub Pages

Select GitHub Pages
GitHub Pages is a static site hosting service provided by GitHub. By using this service, you can publish HTML files and other files stored in your repository as web pages. Access the repository's settings page and enable this service in the "GitHub Pages" section.

Configuring the Workflow

Access GitHub Actions
From the repository's top page, select the "Actions" tab to access the GitHub Actions page.
Search for Workflow Template
Enter the word "Static HTML" in the search box and look for the corresponding template. This template creates a workflow for hosting HTML files on GitHub Pages.
Create the Workflow
Review the contents of the selected template and make edits if necessary. For this workshop, we will use the default settings of the template. Click "Commit changes" to create the workflow.
Enter Commit Message
For the commit message, enter a brief description of the changes made. This will make it easier to track the changes later.

Here, we will explain the steps to execute the workflow created using GitHub Actions. This step will help you understand the process of automatically deploying code changes.

Executing the Workflow

Automatic Triggering of the Workflow
The GitHub Actions workflow is automatically triggered by changes committed to the repository. This means that whenever code changes are committed to the repository, the processing will start automatically.
Wait for the Workflow to Complete
The workflow execution should complete within a few tens of seconds. When the processing is finished, a green checkmark will be displayed. Clicking on this checkmark will allow you to view the details of the workflow.
Check the Deployed URL
The workflow details screen displays the URL where the page is published on GitHub Pages. Click on this URL to check the deployed web page.
Verify the Web Page
If the deployed web page is displayed correctly, it means the deployment of the web page using GitHub Actions was successful.

Detailed Verification of the Workflow

Check the Deploy Job
In the workflow details screen, clicking on the job named Deploy allows you to see in detail what kind of processing was performed. Here, you can see the specific steps of how the web page was deployed.
Check Usage and Workflow File
You can also check detailed information about the workflow execution in the "Usage" and "Workflow file" sections. This information serves as an important reference for understanding the behavior of the workflow and making future adjustments and improvements.

As we progress through the GitHub Actions hands-on workshop, let's now add a new process to the workflow. In this section, we will explain how to incorporate a step into the workflow that uses a link checking tool called lychee to verify if the links in the HTML file are functioning correctly. Performing link validation can improve the quality and reliability of the web page.

Editing the Workflow File

Location of the Workflow File
The GitHub Actions workflow files are located in the .github/workflows directory. Open this directory from the repository's top page and find the workflow file you want to edit.
Selecting the Workflow File
This time, we will edit the static.yml file. After opening the file, click the pencil icon on the right to enter edit mode.
Adding the lychee Action
In the pane on the right side of the editing screen, search for and select a link checking tool called lychee from the marketplace. We will use the "Lychee Broken Link Checker" action with the most stars.
Adding to the Workflow File
Copy the configuration example of the lychee action and add it to the static.yml file. This step includes the settings for performing link checking.
```
- name: Lychee Broken Link Checker
  uses: lycheeverse/lychee-action@v1.9.3
```
Committing the Changes
After making the changes, enter a commit message and commit the changes to the repository. This operation will automatically trigger the workflow, which now includes the new link checking process.

Verifying the Workflow Execution

Automatic Execution of the Workflow
After committing the changes, the workflow will be automatically re-executed. Confirm that the newly added link checking process is also being executed this time.
Checking the Link Checking Results
Confirm that the link checking job is being executed and check the results to see if there are any issues. This process verifies if the links within the web page are functioning correctly.

Detailed Verification of the Workflow

Checking the Link Checking Results
In the workflow details screen, clicking on the job named "Lychee Broken Link Checker" allows you to see in detail what kind of processing was performed. Here, you can see the specific steps of how the link checking was performed.
Checking the Deployment Results
After the link checking, confirm that the deployment job is being executed and check the results to see if there are any issues. This process verifies if the web page is being deployed correctly.

Now, let's move on to branch protection. While workflows like link checking can prevent some mistakes, it's still important for team members to properly review and check if CI/CD is being executed before code is merged. Therefore, by setting branch protection rules, you can manage your team's development process more securely. By utilizing this feature, you can prevent shared environments from being destroyed by erroneous operations and manage your team's development process more securely. The following explains in detail the procedure for setting up branch protection on GitHub.

Setting up branch protection rules

Access settings From the repository's top page, go to the "Settings" tab and select "Rulesets" within the "Rules" section.
Create a new branch protection rule Click the "New ruleset" button to start creating a new branch protection rule.
Configure the ruleset Specify the name of the ruleset and set "Enforcement status" to "Active". For the target branch, select "Include default branch" to protect the "main" branch. Leave the bypass list empty so that no one can bypass the rules.
Approval requirements In the "Required approvals" section, select "Require pull request reviews before merging" and set the number of approvals required for merging. For the hands-on, we'll set it to 0 for self-approval, but for actual projects, 1 or more is recommended.
Block force pushes Enable the "Block force pushes" option to prevent forced pushes and ensure a safe development process.
Create the ruleset After reviewing all the settings, click the "Create" button to create the branch protection rule. By following these steps, you can effectively protect branches in your GitHub repository and ensure a secure development environment. Branch protection rules are an important feature that safeguards your project from unintended operations and inappropriate changes. Set up appropriate protection rules according to your project's needs.

When managing a project using GitHub, setting up branch protection rules can prevent unintended changes and maintain quality. Here, we'll carefully explain the process of verifying that the configured branch protection rules are functioning correctly and the steps to safely make changes through pull requests.

Verifying the effectiveness of branch protection rules

After setting up branch protection rules, it's important to verify that the rules are functioning as expected. If the rules are effective, direct updates to the main branch will be restricted, and creating and merging pull requests will be mandatory to make changes. Follow these steps to verify the effectiveness of branch protection rules:

Verifying the link check workflow: Simultaneously check if the previously added link check GitHub Actions workflow is functioning correctly. Test if the workflow responds appropriately by intentionally making changes that fail the link check.
Editing index.html and committing: Edit the index.html file and make changes that will fail the link check.
```
<a href="broken-link!">Link</a>
```
When you try to commit and push this change, a warning message "You can't commit to main because it is a protected branch." will be displayed, confirming that direct changes are prohibited.
Creating a new branch and making changes: Since you can't make changes directly to the main branch, create a new branch and make changes there.
Creating a pull request and merging: Create a pull request from the new branch with changes and merge it. This safely integrates the changes into the main branch. Now, once merged, the GitHub Actions workflow will be executed immediately. After the latest changes to the project are applied, I recommend reviewing the results of the automatic checks by GitHub Actions. Here, we found a slightly concerning issue. Despite discovering a problem with link validation (Errors: 1), the system judged the overall check as "successful" and proceeded to the next step. This means that a deployment process that shouldn't have been executed was carried out. This phenomenon suggests that there may be an error in the configuration. When working with GitHub Actions, especially when using open-source actions from the marketplace, it's crucial to accurately understand how they function. In this case, a page containing an invalid link was deployed, resulting in a 404 error when the link is clicked. This is not a desirable outcome for site visitors. To prevent such situations, the next step is to review the GitHub Actions settings and modify them to automatically stop deployment if errors are found during the link check. This will help maintain the site's quality and provide a good experience for visitors. So, let's edit the GitHub Actions workflow next to fix it so that deployment doesn't occur if the link check fails.

Next, we'll work on editing the workflow. Currently, we're using an action called "lychee Broken Link Checker" for link checking. However, with the default settings, this action continues the workflow even if the link check fails. Therefore, we need to modify it so that deployment doesn't happen if the link check fails. First, let's refer to the documentation of the "Lychee Broken Link Checker" action and check the available configuration options. In this case, I recommend adding the following configuration:

with:
  fail: true

Screenshot of workflow configuration change Commit the modified workflow. Screenshot of committing the workflow Once the editing is complete, create a pull request. Screenshot of creating a pull request Screenshot of pull request details [Reference] Before merging, you can review the changes from the "Files changed" tab. Screenshot of reviewing changes [Reference] If branch protection is enabled, especially if the number of approvers is set to 1 or more, a review by someone other than yourself is required. You can't "Approve" yourself, only "Comment" is possible, but remember that the steps for review approval and merging can be done from this screen. Screenshot of the need for review approval Perform the merge. Screenshot of executing the merge After the merge is complete, the workflow will be automatically executed. Screenshot of workflow execution Verify that if the link check fails, the workflow stops and deployment doesn't occur. Screenshot of verifying workflow stoppage

In GitHub, the feature to ensure code quality through Pull Requests is very useful, but additional reviews may be required at the deployment stage of the CI/CD process after merging. To address such needs, GitHub provides a feature called "Environments". This allows you to control deployments to specific environments and ensure further safety.

Setting up Environments protection

The following are the steps to set up protection for the github-pages environment.

Access Environments settings: Go to the project's Settings and select the Environments section. This section displays a list of already created environments.
Edit environment protection settings: Click on the github-pages environment to proceed to the detailed settings screen. Here, you can configure the required reviews before deploying to a specific environment.
Add reviewers: In the Required reviewers section, add yourself as a reviewer. This makes your own review mandatory before deploying to the corresponding environment.

Verifying the effect of protection settings

Once the protection settings are complete, proceed with the actual CI/CD process and verify that a review is required before deploying to the github-pages environment. This means that after merging a Pull Request, the automatic deployment process will require approval from the configured reviewers. By utilizing Environments protection settings in this way, you can implement additional safety measures not only for code merging but also for the deployment process. This enables you to further enhance the quality of deployments and contributes to achieving a secure development flow. It's important to properly utilize GitHub Actions and Environments protection features to maintain security and quality throughout the entire development process. Let's make use of these features and aim for more reliable software development.

Next, let's verify that the Environments protection is set up correctly. This time, since we intentionally failed the link check earlier, we'll make changes to fix it and create a Pull Request. Go back to index.html and fix the link. Specify an appropriate URL. When doing so, I recommend specifying a link destination that is reachable from the GitHub Actions Runner.

<a href="https://github.com">Link to GitHub</a>

Commit the edit and create a new Pull Request. Let's merge the pull request. Now, let's check if the Environments protection settings are functioning correctly. The workflow is being executed, but the deployment to github-pages hasn't been performed yet. The process is stopped midway, and approval is required. Now, let's try approving. Click on Review deployment. Now, let's perform the approval. This time, we'll do a self-approval. After that, the deployment process will resume. Witness the successful completion of the deployment process and confirm that it finishes. If successful, a screen like the following will be displayed. Access the site and verify that the link is working correctly.

Now, let's move on to splitting the workflow. In this case, since the workflow is simple, splitting may not be strictly necessary, but as workflows become more complex, splitting can improve readability and maintainability. This time, we'll split the link check and deployment processes, and make the deployment process run after the link check process. Also, if the link check process fails, we'll make it so that the deployment workflow itself doesn't run, and the Environments protection settings will only apply to the deployment workflow. Edit the GitHub Actions workflow. This time, we'll add jobs named test and deploy under Jobs. I'll show the answer yaml file on the next page, but for those who want to challenge themselves, try splitting the workflow on your own while comparing with the images, without looking at the answer. Add jobs named test and deploy under Jobs, and move the corresponding Steps inside them. This time, we'll use the condition notation needs: test to make the deployment process run only if the link check process succeeds. Once the editing is done, commit the changes. After editing, create a new Pull Request. Now, merge the pull request and confirm that the changes are reflected and the new workflow is executed. Can you see that it's executed in two stages as shown below? As shown below, you can confirm that the deployment process is executed only if the preceding link check process succeeds. At the same time, you can see that the deployment process is stopped midway because the Environments protection settings are applied to it. Check the execution details and confirm that only the test is being run. Once you approve the deployment, the deployment will resume.

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false
jobs:
  # Single deploy job since we're just deploying
  test:
    runs-on: ubuntu-latest
    steps:      
      - name: Checkout
        uses: actions/checkout@v4
      - name: Lychee Broken Link Checker
        uses: lycheeverse/lychee-action@v1.9.3
        with:
          fail: true
  # Single deploy job since we're just deploying
  deploy:
    needs: test
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Now, this is the last part. Finally, we'll make the link check run when a pull request is made. So far, we've added the link check process to the workflow for deploying to GitHub Pages, but ideally, we want to run the link check before merging, right? This time, we'll add a workflow so that the link check process is executed when a pull request is created before it's merged. First, let's add a new workflow. Click on Create new file, set the file name to link-check.yml, and enter the following content. Again, for those who want to challenge themselves, try creating the workflow on your own while comparing with the images, without looking at the answer. The key point here is that the trigger condition for the workflow is pull_request. This makes the link check process run when a pull request is created.

on:
  pull_request:
    types: [opened, reopened]

Now, once the editing is successful, let's create a pull request again. Now, after creating it, wait a bit before merging. Something different from before is happening. You can see that the link check is being executed.

If you click on Details for the link check, you can go to the execution screen. Let's confirm that the Link Check action is working properly. Now, if you can confirm, it says "All checks have passed". This means you can safely merge. Once confirmed, go ahead and merge. Finally, we will check the behavior when the link check "fails" during a pull request and end the hands-on. So, let's break the link in index.html that we just fixed. After breaking the link, create a pull request again. After creating the pull request, the link check will be executed. If the link check fails successfully, the pull request screen will also display that it failed. Let's confirm that it failed.

# Simple workflow for deploying static content to GitHub Pages 
name: Link Check
on:
  pull_request:
    types: [opened, reopened]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:  
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write 
  id-token: write
jobs:
  # Single deploy job since we're just deploying
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Lychee Broken Link Checker
        uses: lycheeverse/lychee-action@v1.9.3
        with:
          fail: true

Joining the Organization

Creating a Repository

Creating the index.html File

Setting Up GitHub Pages

Configuring the Workflow

Executing the Workflow

Detailed Verification of the Workflow

Editing the Workflow File

Verifying the Workflow Execution

Detailed Verification of the Workflow

Setting up branch protection rules

Verifying the effectiveness of branch protection rules

Setting up Environments protection

Verifying the effect of protection settings

Creating the `index.html` File