# Using & Contributing to This Repository

## Overview

This repository provides a centralized set of actions for simplifying development processes across repositories. The primary principle is using a single workflow step that references one of our actions, allowing centralized maintenance.

**Action Types:**
* **Workflow actions**: Used as a single step in workflow files
* **Reusable actions**: Used within other actions or workflows

## Repository Structure

* `actions` - Reusable actions for repositories and workflows
* `scripts` - Utility scripts for actions
* `dependencies` - Runtime dependencies (primarily Python)
* `workflows` - Examples for workflow actions

## For Users

> ⚠️ **IMPORTANT**: Always use tagged releases in production workflows:
> * Major version tags: `v1` (auto-updates to latest v1.x.x)
> * Exact version tags: `v1.0.5` (fixed version)

> ⚠️ **WARNING**: Avoid using `main` branch references in workflows as they may be unstable.

## For Contributors

### Getting Started

1. Create a branch from `main` named after your Jira ticket
2. In consumer repos, create matching branch and reference your action branch: `perimeter-81/actions/actions/some/action/name@<branch-name>`
3. Create `actions.yaml` in your action's directory
4. Check for similar existing actions before adding new functionality

### Coding Guidelines

* Add `README.md` for reusable actions (see [actions/aws/assume_role_v2](actions/aws/assume_role_v2/README.md) for examples)
* To resolve `ROOT_PATH` environment variable properly use this example:
  ```yaml
  - name: set action env vars
    id: root_path
    run: |
      cd ${{ github.action_path }}/../../..
      echo "path=$(pwd)" >> $GITHUB_OUTPUT
    shell: bash
  
  - name: Run script
    run: |
      python $ROOT_PATH/scripts/example.py
    env:
      ROOT_PATH: ${{ steps.root_path.outputs.path }}
  ```
* For Python scripts:
  * Import the standard logger: `from actions_logging.logging import logger` 
  * Add type hints and docstrings
  * Use `if __name__ == "__main__":` pattern
  * Reuse existing methods where possible
* For Bash scripts:
  * Include: `#!/bin/bash source "$ROOT_PATH"/scripts/common.sh`
  * Use utilities from `common.sh` like `echo_red`, `echo_green_bg`, and `handle_error`
* Use [Script Runner](actions/setup/script_runner/README.md) for scripts from the `scripts` folder

### Versioning

> ⚠️ **WARNING**: Code in the `main` branch is under active development and less stable than tagged versions.

When releasing, use the [tag creation workflow](https://github.com/perimeter-81/actions/actions/workflows/create_tag_and_release.yaml)

> ⚠️ **IMPORTANT**: Use version format: `vX.Y.Z` for release

The workflow updates `main` branch references to specific version tags and creates relevant Git tags and GitHub releases.

## Development Setup

### Local Environment

```bash
pyenv use 3.11
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r actions/dependencies/requirements.txt
```

### Code Quality Tools

This project uses pre-commit hooks with:
- **autoflake**: Removes unused imports
- **isort**: Sorts imports
- **black**: Formats code (line length: 120)
- **flake8**: Lints code

**Setup:**
```bash
pip install pre-commit
pre-commit install
```

**Configuration Files:**
* `.pre-commit-config.yaml`: Hook configurations
* `pyproject.toml`: Black and isort settings
* `.flake8`: Flake8 settings

### VS Code Configuration

Example `.vscode/launch.json`:
```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Some action debug environment",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "cwd": "${workspaceFolder}/somewhere_where_i_need_to_run_my_action_scripts_from",
            "console": "integratedTerminal",
            "env": {
                // workflow inputs or environment variables set during action execution that are business-logic related
                "ENV_NAME": "bb8",
                "KEY": "VALUE", // optional, depends on the flow debugged
                // Debugging vars
                "PYTHONPATH": "${workspaceFolder}/actions/scripts/:$PYTHONPATH", // required for python to be able to recognize imports
                "LOG_LEVEL": "DEBUG", // optional
                //  Vars set by Github and used in workflow
                "GITHUB_REPOSITORY": "perimeter-81/devops-terraform-ga", // optional
                "GITHUB_ENV": "/tmp/githubenv.txt", // mandatory
                "GITHUB_OUTPUT": "/tmp/githuboutput.txt", // mandatory
                "GITHUB_STEP_SUMMARY": "/tmp/githubsummary.txt", // mandatory
                // assume your AWS role if needed the aws credentials, or find another way to provide AWS credentials to your local runtime if you need them
                "AWS_ACCESS_KEY_ID": "***",
                "AWS_SECRET_ACCESS_KEY": "***",
                "AWS_SESSION_TOKEN": "***",
            }
        },
    ]
}
```

[Full local setup example](https://perimeter81.atlassian.net/wiki/spaces/RD/pages/997032006/GitOps+IaC+pipeline+local+development)