feat: add github action wf doc (#12)

docs/github_actions_reusable_workflows.md

@@ -0,0 +1,53 @@
+# Using GitHub Action Reusable Workflows
+
+## Introduction
+
+GitHub Actions is a powerful automation tool that allows developers to create workflows for continuous integration and continuous deployment (CI/CD). One of the key features of GitHub Actions is the ability to create reusable workflows, which can help streamline your CI/CD processes by allowing you to define a workflow once and reuse it across multiple repositories or workflows. This guide will provide an overview of how to use reusable workflows in GitHub Actions, including prerequisites, a breakdown of the workflow sections, a fully working example, and a discussion of the pros and cons.
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+1. A GitHub account and access to a repository where you can create workflows.
+2. Basic knowledge of YAML syntax and GitHub Actions.
+3. Familiarity with Terraform, as the example provided will involve Terraform workflows.
+
+## Understanding GitHub Actions Sections
+
+A GitHub Actions workflow is defined in a YAML file and consists of several key sections:
+
+- **name**: This specifies the name of the workflow.
+- **on**: This section defines the events that trigger the workflow, such as `push`, `pull_request`, or `workflow_call` for reusable workflows.
+- **jobs**: This section contains one or more jobs that define the tasks to be executed. Each job can run on different environments and can depend on other jobs.
+- **steps**: Each job consists of a series of steps that can include actions, commands, or scripts to be executed.
+
+## Example: Reusable Workflow
+
+Below is a fully working example of a reusable GitHub Actions workflow for validating Terraform configurations.
+
+### Reusable Workflow (tf-validate.yaml)
+
+https://github.com/saidsef/saidsef/blob/a8854ba31beb489bae5cbac0312959d0017a0639/.github/workflows/tf-validate.yaml#L1-L101
+
+### Calling the Reusable Workflow
+
+To use the reusable workflow defined above, you can create another workflow file that calls it. Below is an example of how to do this:
+
+https://github.com/saidsef/terraform-aws-github-oidc/blob/b1e483aad6e8b8c64ccc1890bbc1340abcd303ae/.github/workflows/ci.yaml#L1-L29
+
+## Pros and Cons
+
+### Pros
+
+- **Reusability**: Define a workflow once and reuse it across multiple repositories or workflows, reducing duplication.
+- **Maintainability**: Changes made to the reusable workflow are automatically reflected in all workflows that use it.
+- **Modularity**: Break down complex workflows into smaller, manageable components.
+
+### Cons
+
+- **Complexity**: Understanding and managing reusable workflows can add complexity, especially for beginners.
+- **Debugging**: Debugging issues in reusable workflows may be more challenging, as the workflow is abstracted away from the main workflow file.
+
+## Conclusion
+
+Reusable workflows in GitHub Actions provide a powerful way to streamline your CI/CD processes by allowing you to define workflows once and reuse them across multiple projects. By following the guidelines outlined in this documentation, you can effectively implement reusable workflows in your projects, enhancing maintainability and reducing redundancy. As with any tool, it is essential to weigh the pros and cons to determine if reusable workflows are the right fit for your development process.