Accessibility and Navigation

There are several methods for navigating through the chapters (i.e., sessions).

The sidebar on the left provides a list of all chapters/sessions. Clicking on any of the chapter/session titles will load that page.

The sidebar may not automatically appear if the window is too narrow, particularly on mobile displays. In that situation, the menu icon () at the top-left of the page can be pressed to open and close the sidebar.

The arrow buttons at the bottom of the page can be used to navigate to the previous or the next chapter.

The left and right arrow keys on the keyboard can be used to navigate to the previous or the next chapter.

Top menu bar

The menu bar at the top of the page provides some icons for interacting with the book. The icons displayed will depend on the settings of how the book was generated.

Tapping the menu bar will scroll the page to the top.

Search

Each book has a built-in search system. Pressing the search icon () in the menu bar, or pressing the S key on the keyboard will open an input box for entering search terms. Typing some terms will show matching chapters and sections in real time.

Clicking any of the results will jump to that section. The up and down arrow keys can be used to navigate the results, and enter will open the highlighted section.

After loading a search result, the matching search terms will be highlighted in the text. Clicking a highlighted word or pressing the Esc key will remove the highlighting.

You have the ability to change the theme of the mdBook by clicking the icon on the top left mdBook. Additionally, there is a toggle for the table of content, and a search tool.

Issues

If you notice a mistake you can notify me, Ali Jaddoa (at Ali.Jaddoa@Reohampton.ac.uk) so I can make the correction.

Printing

Currently the mdBook is approximately 60+ pages, and the environmental impact per page ~10.2L water, 2g CO\(_2\) and 2g wood. Therefore, ~600L water, 120g CO\(_2\) and 120g wood would be needed to produce a paper copy of this mdBook.

The environmental effects of paper production include deforestation, the use of enormous amounts of energy and water as well as air pollution and waste problems. Paper accounts for around 26% of total waste at landfills

Therefore, please print only if this is really necessary.

Author: Dr Ali Jaddoa
Email: Ali.Jaddoa@roehampton.ac.uk

Thank you for reading this MDBook. If you have any questions or suggestions, feel free to reach out.

MSc Project -CMP060L050H: Workshop 3

Part-1 GitHub Basics: Setting Up Git and GitHub

In this set of activities, you will get hands-on experience with Git and GitHub, which are essential tools for managing and tracking changes in your code, documentation, and data. These skills are widely used in industry and academia and will support your MSc final project.

Step 1: Create a GitHub Account

GitHub is a cloud-based platform that allows you to store and manage your code, track changes over time, and collaborate with others. It’s widely used in both academia and industry.

If you don't have an account already, please follow the instructions below:

1. Go to https://github.com/join
2. Choose a professional username, such as firstname-lastname or student-ID
3. Use your university email address to access educational features (e.g. private repositories, GitHub Student Developer Pack). You can link it to mutiple emails later.
4. Choose a secure password and complete the sign-up form
5. Verify your email address to activate your account

Why this matters:
You will use GitHub to store your MSc project work, track your progress, and possibly collaborate with others. Starting with a well-named, verified account sets you up for future success.

Step 2: Install and Configure Git

Git is a version control system that allows you to manage your project files over time. It keeps track of every change you make, so you can revisit earlier versions, collaborate with others, and avoid losing work.

Install Git

Install Git based on your operating system:

• Windows: Download and install from https://git-scm.com/download/win
  During installation, accept the default settings. This will also install Git Bash, which You will use as your terminal.

• macOS: Download and install from https://git-scm.com/download/mac
  Alternatively, open the Terminal and type:

  xcode-select --install
  

• Linux (Ubuntu/Debian):

  sudo apt update
  sudo apt install git
  

Open Your Terminal

• On Windows, open Git Bash from the Start Menu
• On macOS/Linux , open the Terminal application from Launchpad or Spotlight

Verify Git Installation

Check that Git is installed by typing:

git --version

Configure Git (One-Time Setup)

Now set your name and email. This information will be recorded in every change you make:

git config --global user.name "Your Full Name"
git config --global user.email "your.email@example.com"

Check your configuration with:

git config --list

Further Reading

To learn more about Git commands and concepts, visit the official documentation: https://git-scm.com/doc

Why this matters:
Git needs to know who you are to track your work. Setting this up ensures your commits are properly attributed and helps when collaborating with others.

Step 3: Create a New Repository on GitHub

A repository (or "repo") is a project folder on GitHub. It holds all your code, documentation, and version history. You can create one to store your MSc coursework, dissertation code, notes, or even experiment logs.

Create a New Repository

1. Go to https://github.com/new and sign in if needed.

2. Fill in the following:

   • Repository name: git-practice-lab (or a name relevant to your project)
   • Description: Optional, but useful for summarising the purpose of the repo
   • Visibility: Select Private so only you (and optionally your lecturer) can access it
   • Tick the box "Initialize this repository with a README"

3. Click Create repository

GitHub will set up your repository and take you to its main page. You will see your README.md file, commit history (currently just one), and options for cloning the repo to your computer.

Explore Repository Settings

After creating the repository:

1. Click on the Settings tab (usually found in the top menu of the repo page).
2. Take a few minutes to explore:
   • General settings like repo name, visibility, and description
   • Branches to manage default branches and protection rules
   • Collaborators (you can add contributors if needed later)
   • Pages, Webhooks, and other features

Why this matters:
Creating your own repository gives you full control over your project. You can store scripts, datasets, results, and documentation all in one place, and access it from anywhere.

Step 4: Clone the Repository to Your Machine

To work on your GitHub project locally (on your own machine), you need to clone the repository. Cloning downloads the files and Git history into a folder on your computer.

You have two options:

Option A: Use the Repository You Just Created

1. Open your repository on GitHub
2. Click the green Code button and copy the URL under HTTPS

Example:

https://github.com/your-username/git-practice-lab.git

Option B: Use a GitHub Classroom Repository

• For this session, I have set up a GitHub Classroom that will automatically create a private repository linked to your GitHub account.
• Please click https://classroom.github.com/a/qqntlbBw and follow the on-screen instructions to join the assignment.
• Once your personal repository is created:
  1. Open your newly created GitHub Classroom repository in your browser
  2. Click the green Code button and copy the URL under HTTPS

Clone Using the Command Line (Git Bash / Terminal)

Open your terminal (Git Bash for Windows, Terminal for macOS).

Then run the following command, replacing the URL with the one you copied earlier from the Code button on GitHub:

git clone https://github.com/your-username/repository-name.git

For example, if you copied:

https://github.com/your-username/git-practice-lab.git

You would type:

git clone https://github.com/your-username/git-practice-lab.git

Then move into the project folder:

cd git-practice-lab

This creates a local folder on your machine containing the contents of your GitHub repository.

Clone Using Visual Studio Code

1. Open Visual Studio Code (or you can download from here)
2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
3. Type and select: Git: Clone
4. Paste the repository URL you copied earlier
5. Choose a folder on your machine to save the cloned project
6. Click Open when prompted

VS Code will now treat this folder as your working project, connected to Git.

Why this matters:
Cloning connects your local machine with your GitHub repository. This allows you to work offline, use your preferred tools, and then push changes back to the cloud for backup, version tracking, or collaboration.

Note:
If you don’t want to install anything on your machine, you can also try GitHub Codespaces (if enabled). It’s like a full coding environment in your browser, it is useful for quick edits or working from different devices.

Look for the "Code" > "Open with Codespaces" option in your repository.

More info can be found here

Step 5: Basic Git Workflow

Once you’ve cloned your repository, you can start working on it locally. Git tracks every change you make, allowing you to manage versions, backtrack if needed, and collaborate effectively.

You can use either the command line or Visual Studio Code GUI.

Option A: Using the Command Line

1. Create a new file named about-me.md:

   touch about-me.md
   

2. Open the file in a text editor and write a short paragraph about yourself. For example:

   My name is [Your Name].
   I am studying MSc in [Your Course].
   I am interested in [e.g. cybersecurity, data analysis, AI].
   

   You can open it using:

   • notepad about-me.md on Windows (Git Bash)
   • open -a TextEdit about-me.md on macOS
   • nano about-me.md or code about-me.md if using VS Code or terminal editors

3. Stage the file (tell Git to track it):

   git add about-me.md
   

4. Commit the file with a message:

   git commit -m "Add about-me file"
   

5. Push your changes to GitHub:

   git push
   

6. View the file in your GitHub repository online to confirm the update.

Option B: Using Visual Studio Code

1. Open the cloned repository folder in VS Code
2. Create a new file named about-me.md and write something inside it
3. Click the Source Control icon on the sidebar
4. Stage the file by clicking the + next to its name
5. Enter a commit message (e.g., “Add about-me file”) and click the checkmark to commit
6. Click the ... (three-dot menu) and choose Push

Why this matters:
These steps make up the core Git workflow. You will use them repeatedly throughout your MSc project to save progress, sync with GitHub, and keep your work organised and secure.

Step 6: Create and Merge a Branch

You can skip this and move to Github Actions

In Git, a branch is a separate workspace that allows you to make changes without affecting the main version of your project. This is useful for testing new ideas or working on features before you're ready to add them to the main branch (usually called main or master).

Why this matters:

Branches help you experiment, manage features separately, and avoid breaking your main work. This is especially useful during your MSc project when you may want to try different approaches without disrupting your core work.

Option A: Using the Command Line

1. Create a new branch

From your terminal:

git checkout -b feature/intro

This creates a new branch called feature/intro and switches to it.

2. Create a new file and add some content

touch intro.txt

Then open it and add something like:

This is a test file created on a separate branch.

Save the file.

3. Stage and commit the file

git add intro.txt
git commit -m "Add intro.txt on feature branch"

4. Push the branch to GitHub

git push --set-upstream origin feature/intro

5. Open a Pull Request (PR)

1. Go to your repository on GitHub.
2. You will see a prompt to compare & create a pull request for feature/intro.
3. Click Compare & pull request, review the changes, and click Merge pull request.
4. You can now delete the branch on GitHub after merging if prompted.

Option B: Using Visual Studio Code

1. Open your project folder in VS Code

2. Click on the Source Control icon (or press Ctrl+Shift+G)

3. At the bottom left of the window, click the current branch name (e.g. main)

4. In the branch menu that appears:

   • Click + Create new branch
   • Name it feature/intro
   • VS Code will automatically switch you to this new branch

5. Create a new file called intro.txt and write:

   This is a test file created on a separate branch.
   

6. Save the file, then stage and commit it via the Source Control panel:

   • Click the + to stage
   • Enter your commit message (e.g., “Add intro.txt on feature branch”)
   • Click the checkmark to commit

7. Push the branch:

   • Click the ... (three-dot menu)
   • Select Push

8. Open GitHub in your browser

   • You’ll see a prompt to open a Pull Request
   • Click Compare & pull request, then Merge pull request

Common Git Commands Overview

Extra:

Below you can learn more about:

• GitHub
• Branching

Author: Dr Ali Jaddoa
Email: Ali.Jaddoa@roehampton.ac.uk

Thank you for reading this MDBook. If you have any questions or suggestions, feel free to reach out.

MSc Project -CMP060L050H: Workshop 3

ALi JAddoa

Part-2: Automating Your GitHub Project with GitHub Actions

GitHub Actions lets you automate tasks in your repositories. In this lab, you will create workflows to automate project tracking, verify structure, and flag incomplete tasks using Actions written in YAML (check it (YAML) out here ).

Create the Workflow Directory

1. In your GitHub repository, click Add file > Create new file (or you can create the file however you like)
2. Name the file:

   .github/workflows/hello-world.yml
   

Action 1: Your First GitHub Action – Hello World

name: Hello World

on: 
  push:

jobs:
  say-hello:
    runs-on: ubuntu-latest

    steps:
      - name: Print a greeting
        run: echo "Hello, World! This is your first GitHub Action."

What it does: Runs on every push and prints a greeting in the Actions log.

Check and View the Action

1. Navigate to the Actions tab in your GitHub repository
2. Click on the Hello World workflow run
3. Expand the say-hello job and the Print a greeting step

You should see:

Hello, World! This is your first GitHub Action.

This confirms that your Action executed successfully.

Action 2: Automate Weekly Log Creation

In this task, you will automate the creation of a weekly project log. Every Monday morning, GitHub Actions will generate a new Markdown file with a predefined structure to help you track your progress, document challenges, and plan upcoming tasks.

This kind of automation is especially useful for managing MSc projects, dissertations, or team-based collaboration work. You will also learn how to schedule tasks using cron syntax and configure auto-commits via GitHub Actions.

Instructions

1. Create a new workflow file

1. In your GitHub repository, click Add file > Create new file
2. Name the file:

   .github/workflows/weekly-log.yml
   

2. Use the following YAML

name: Weekly Log Generator

on:
  schedule:
    - cron: '0 9 * * 1'  # Runs every Monday at 09:00 UTC
  workflow_dispatch:      # Allows manual triggering from the Actions tab

jobs:
  generate-log:
    runs-on: ubuntu-latest

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

      - name: Create weekly log file
        run: |
          FILE_NAME="weekly-log-$(date +'%Y-%m-%d').md"
          echo "# Weekly Log - $(date +'%A, %d %B %Y')" > $FILE_NAME
          echo "- Tasks completed:" >> $FILE_NAME
          echo "- Challenges faced:" >> $FILE_NAME
          echo "- Plans for next week:" >> $FILE_NAME

      - name: Commit and push log file
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add *.md
          git commit -m "Add weekly log $(date +'%Y-%m-%d')"
          git push

Note on Scheduling

Choose a time close to now for testing.

For example, today is Wedensday (which is 3 in cron), and the time is 10:30, then use:

cron: '35 10 * * 1'

This will trigger the job at 10:35 UTC. You can also use https://crontab.guru to understand and customise the timing.

3. Commit and test

• Click Commit changes
• Go to the Actions tab
• Select the Weekly Log Generator workflow
• Click Run workflow to trigger it manually

Notes

1. What does cron: '0 9 * * 1' mean?

   The cron value controls when the workflow runs automatically. This is a standard cron expression, which GitHub uses to schedule workflows in UTC time.

   | Field | Value | Description | |---------------|--------|-----------------------------------| | Minute | 0 | At minute 0 | | Hour | 9 | At 09:00 (9 AM) | | Day of Month | * | Every day of the month | | Month | * | Every month | | Day of Week | 1 | On Monday (where Sunday = 0 or 7)|

   Meaning: The action will run every Monday at 09:00 UTC.

   If you're in the UK, note this means:

   • 09:00 local time in winter (GMT)
   • 10:00 local time in summer (BST)

   You can modify the time by changing the values. Use https://crontab.guru to try different schedules and understand how they work.

2. workflow_dispatch: Adds a button in the Actions tab to manually trigger the workflow.

3. Permissions: This will only work if GitHub Actions has push access to your branch. Make sure you're working on a repository you own.

Output

The result will be a new file in your repository like:

weekly-log-2025-06-02.md

With this content:

Weekly Log - Monday, 2 June 2025
- Tasks completed:
- Challenges faced:
- Plans for next week:

You can then edit and fill it in later with updates for your supervisor or your own record-keeping.yaml

Challenge: Try to redo the scehdule action but on push and not using cron

Action 3: Detect TODO Comments and Generate a Markdown Report

In this task, you will use a GitHub Action to automatically scan your code for any TODO comments and generate a Markdown report. This can be useful for tracking unfinished tasks or reminders in your codebase.

What This Workflow Does

• It looks through your project for any lines containing the word TODO
• It creates a file called TODO-Report.md that lists each file and line where a TODO comment is found
• The report is committed and pushed back to your repository

The Workflow File

Create a new file in .github/workflows/todo-scan.yml and paste the following:

name: Detect TODO Comments

on:
  push:

jobs:
  scan-todo:
    runs-on: ubuntu-latest

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

      - name: Search for TODOs and export to Markdown
        run: |
          echo "## TODO Report - $(date)" > TODO-Report.md
          echo "" >> TODO-Report.md
          echo "| File | TODO Comment |" >> TODO-Report.md
          echo "|------|---------------|" >> TODO-Report.md
          grep -rn --exclude-dir=.git "TODO" . | while IFS=: read -r file line content
          do
            printf "| \`%s\` | %s |
" "$file:$line" "$content" >> TODO-Report.md
          done

      - name: Commit and push TODO Report
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add TODO-Report.md
          git commit -m "Update TODO Report - $(date +'%Y-%m-%d')"
          git push

Try It Yourself

1. Open or create a Python file in your repository, for example example.py.
2. Add a TODO comment inside the code. For example:

# TODO: Optimise this logic
def sample_function():
    pass

3. Save the file.

Commit and Push

Now open your terminal and push the changes:

git add .
git commit -m "Added TODO comment"
git push

Check the Action and Report

1. Go to your GitHub repository.
2. Click the Actions tab and open the latest run of "Detect TODO Comments".
3. After it completes, go back to the Code tab and open the newly created file TODO-Report.md.

You should see a table listing your TODO comment with the file and line number.

Extension Task

• Try adding multiple TODOs in different files.
• See how the report automatically updates.
• Experiment with detecting other keywords like FIXME, HACK, or custom tags.

Action4: Automate Visualisation Task – Weekly Security Incidents

Here you will use GitHub Actions to automate the visualisation of weekly cybersecurity incident data. This is a practical way to integrate automation into your MSc project, research activity, or log monitoring routine.

Step 1: Create a Dataset

Add the following file to your repository: File: security_incidents.csv

This dataset reflects common cybersecurity incident types and their frequencies.

Step 2: Add Your Python Script

You have two options:

• Download the script file and place it in your repository
• OR manually create the Python visualisation script using the code below

File: plot_security_incidents.py

import pandas as pd
import matplotlib.pyplot as plt

# Load the dataset
df = pd.read_csv("security_incidents.csv")

# Create a bar chart
plt.figure(figsize=(10, 6))
plt.bar(df["category"], df["incident_count"], color="tomato")

# Add title and labels
plt.title("Weekly Security Incidents by Category")
plt.xlabel("Incident Type")
plt.ylabel("Number of Incidents")
plt.xticks(rotation=45)
plt.grid(axis="y", linestyle="--", alpha=0.7)

# Save output
plt.tight_layout()
plt.savefig("security_incidents_chart.png")

Step 3: Create the GitHub Action

Create the following workflow file to automate the execution of the Python script.

File: .github/workflows/plot_incidents.yml

name: Security Incident Visualisation

on:
  workflow_dispatch:  # Allows manual execution from the Actions tab

jobs:
  generate-chart:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Install Python dependencies
        run: pip install pandas matplotlib

      - name: Run the plotting script
        run: python plot_security_incidents.py

      - name: Commit and push generated chart
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add security_incidents_chart.png
          git commit -m "Auto-generated security incident chart"
          git push

Step 4: Run and Verify

After committing and pushing your changes:

1. Go to the Actions tab in your GitHub repository
2. Select Security Incident Visualisation
3. Click Run workflow

After a short while, you should see the generated chart:

security_incidents_chart.png

This image contains your auto-generated bar chart based on the incident data.

Extra:

Below you can learn more about:

• GitHub Actions
• MS Short Course

Author: Dr Ali Jaddoa
Email: Ali.Jaddoa@roehampton.ac.uk

Thank you for reading this MDBook. If you have any questions or suggestions, feel free to reach out.