Now that you have gained a bit of practical experience, it is time to fully understand
the syntax for workflows. Since workflows are written in YAML, it is important to
fully understand YAML before writing workflows.

# What is YAML

- YAML, which stands for "YAML Ain't Markup Language," is a data-serialization language optimized for human readability and writability. It's a strict superset of JSON but uses syntactically relevant newlines and indentation instead of braces.

# YAML BASIC

To start, it’s essential to understand that YAML files have a `.yml` or `.yaml` extension, which makes them well-suited for version control systems like Git. This is because every change is tracked per line, allowing for efficient versioning.

```yaml
# A full-line comment in YAML

key: value  # An inline comment

```

Comments can appear anywhere in a line

## Data Types :

Alright, here’s the same content in English:

In YAML, there are many data types, both primitive (simple scalars) and complex.

For example:

### Scalar Types

In YAML, we can assign a value to a variable using this syntax:

```yaml
key: value

```

Here, the `key` represents the variable name, and the `value` is its assigned type or value.

To get a better understanding of the context in a project, let's look at this example:

```yaml
name: String
job: String
age: int
address: 
  - zip_code
  - address_name
  - numero
datetime: 1999-12-31T23:59:43.1Z
```

Note that keys and values in YAML can contain spaces and do not require quotation marks! You can use single or double quotes for keys and values, but this is only necessary if they contain special characters or if YAML might misinterpret their data type.

- **Double quotes** (`" "`) use the backslash (`\`) as the escape character.
- **Single quotes** (`' '`) use an additional single quote (`''`) for escaping.

There are cases when we want to write in multiple lines. In YAML syntax, this is done using the pipe operator and a four-space indentation, like in a literal block.

```yaml
description: |
  This is a description that spans multiple lines.
  You can write as much as you want here,
  and each new line will be preserved in the output.
  - Lists can also be included within the block.
  - Each line will start with an indentation.
```

This makes writing complex scripts in YAML workflows much easier than in other formats where you must quote variables

When defining complex data types, YAML provides two types of collections: maps and lists (also known as sequences). 

### Maps

Maps use two spaces of indentation with the same syntax as assigning variables:

```yaml
parent:
  key1: value1
  key2: value2
  child:
    subkey1: subvalue1
    subkey2: subvalue2
```

### Lists (Sequences)

Lists are created using hyphens:

```yaml
fruits:
  - apple
  - banana
  - cherry

nested_list:
  - item1
  - item2:
      - subitem1
      - subitem2
```

Now that we've gotten a glimpse of what YAML can look like, let's return to some interesting topics. 

# Workflows

Now, we'll apply what we've learned so far in the context of GitHub Actions and build a foundation to tackle workflows. 

## The Workflow Syntax

As we know, the first element to start with when tackling a workflow in GitHub Action  is the `name` element. A simple but important piece of information is that the name of the workflow can be different from the name of the file. For example, the file can be called `main.yml`, while the workflow is defined as follows:

```yaml
name: My First Workflow

```

## Events and Triggers

Events and triggers play a central role in building a robust workflow. Identifying when, or based on which events, to trigger the pipeline is a difficult decision to make.

In this section, GitHub Actions provides us with three main categories of triggers.

- Webhook triggers
- Scheduled triggers
- Manual triggers

each triggers follow the key “on : “ in the workflow file 

### Webhook triggers

Here, webhook triggers work within the context of events in GitHub. For example:

Imagine you're working in a complex system with teammates from different team structures, and you want the workflow to start based on a webhook that triggers on a `git push` to the repository.

To achieve this, you can simply add this line of code in your workflow:

```yaml
on: push

```

it can also be a pull request in the repo 

```yaml
on:[push,pull_request]
```

One of the nice features of webhook triggers is that they can be configured based on certain conditions. For example, you can start a workflow only when pushing to specific "branches" or when certain files in a path have been updated. 

For example, in this scenario: 

```yaml
on:
  push:
    branches:
      - main             # Trigger only when pushing to the 'main' branch
    paths:
      - 'src/**'         # Trigger only if files in the 'src/' directory have been modified
```

- We only trigger the pipeline when changes are pushed to the "main" branch.
- We also only trigger the workflow if files in the 'src/' directory have been modified.

These are just some examples of the most frequently used webhook triggers. You can also use many others, allowing you to customize your workflow to better fit your unique use case

## Scheduled triggers

Here we have the schedule triggers. As the name suggests, these triggers start the workflow at a scheduled time—they use the same syntax as cron jobs. The syntax consists of five fields:

1. Minute (0-59)
2. Hour (0-23)
3. Day of month (1-31)
4. Month (1-12 or JAN-DEC)
5. Day of week (0-6 or SUN-SAT)

an example of a schedule trigger in a GitHub Actions workflow:

```yaml
on:
  schedule:
    # Runs every 16th minute
    - cron: '*/16 * * * *'
    # Runs every hour from 10 AM to 3 PM
    - cron: '0 10-15 * * *'
    # Runs every Friday at midnight
    - cron: '0 0 * * FRI'
    # Runs every quarter (at 00:00 on day 1 of every 3rd month)
    - cron: '0 0 1 */3 *'

```

As you can see here, we can combine multiple scheduling options in the same workflow, which can be helpful for running the workflow in batch mode

### **Manual Triggers**

Finally, the last type is **Manual Triggers**. These allow you to start a workflow manually.

The syntax for a manual trigger can look like this:

```yaml
on: workflow_dispatch

```

In this case, the trigger has one input: the branch the workflow runs on. The default branch is usually the `main` branch. You can use the GitHub UI to trigger the workflow manually, where you will be presented with a dialog to start the workflow."

![image.png](https://prod-files-secure.s3.us-west-2.amazonaws.com/c26cbd8c-4ae9-4ab6-b595-99bb653f9d83/09abe19e-4933-4b1d-a037-f94e0a53e280/image.png)

You can also trigger the GitHub workflow using the GitHub CLI, either by name, ID, or relative file name to `.github/workflows`:

```bash
$ gh workflow run WORKFLOW_FILENAME
```"
```

### Workflow jobs and steps

Here, the logic of the workflow is defined in the `jobs` section. As we know, each job is executed on a runner. The runner can either be self-hosted, or you can choose one from the cloud.

Make sure to use the latest version of the runner, such as `ubuntu-latest`, `windows-latest`, or `macos-latest`, but always remember the cost factor.

| **Operating System** | **Price** |
| --- | --- |
| Linux | $0.008 |
| macOS | $0.08 |
| Windows | $0.016 |

### Workflow jobs

As we defined previously, jobs are the units of work here; they run in parallel by default.

You can chain them in a sequence by having a job depend on the successful output of one or multiple other jobs using the `needs` keyword

Q- given all the context here so far and my oun khnwolde 

Q- i just create a github Repo like this 

https://github.com/AmirUpSkill/GitHub-Action-HandsOn.git

This is my repository to test proof of concept GitHub Action workflows in different stacks (FastAPI, Node.js, Spring Boot, and more)

Q- as you can see we need to build a simple poc workflow okii 

Q- with different stack the first one is fast api okii 

Q- okii so help me to creat this tutor 

Q- use step by step style form clone the repo 

Q- to create the FastApi-Workflow 

Q- initate the python venv venv 

Q- install the packgest need it herre 

Q- freeze them inside the requirements.txt 

Q- create simple folder strutre 

Q- create a simple rest api 

Q- and create a simple unit test to this api 

Q- then create main workflow 

Q- and show my how this workflow diclant when just change the resturn string from github

form “Hello , This A Simple Prof Of Concept V1” to become 

“Hello , This A Simple Prof Of Concept V1” 

Q- do it at software level engineer oki