docs: update documentation for new features and add authentication guides

- Add step-by-step token creation guides for GitLab, GitHub, Bitbucket, CodeCommit, SSH
- Document retry, exclude branches, parallel, and pre-check features
- Add new workflow examples (exclude branches, parallel with retry)
- Update project structure and coverage info in development guide
- Update README with new features and inputs

Author: somaz94

README.md

@@ -15,11 +15,15 @@ A Go-based GitHub Action that mirrors repositories to multiple Git hosting provi
 - Multi-target mirroring in a single workflow step
 - Auto-detect provider from URL (GitLab, GitHub, Bitbucket, CodeCommit)
 - Selective branch mirroring or mirror all branches
+- Exclude specific branches from mirroring
 - Tag mirroring support
 - Force push option for exact replication
 - Multiple authentication methods (token, app password, SSH key)
-- Dry run mode for safe testing
+- Parallel mirroring to multiple targets concurrently
+- Retry logic with configurable count and delay
+- Dry run mode with remote connectivity pre-check (`git ls-remote`)
 - JSON result output for downstream steps
+- Credential masking in all log output
 
 > For detailed documentation, see the [docs/](docs/) folder:
 > [Authentication](docs/AUTHENTICATION.md) |
@@ -166,7 +170,11 @@ jobs:
 | `mirror_branches` | Branches to mirror (comma-separated, or `all`) | No | `all` |
 | `mirror_tags` | Mirror tags | No | `true` |
 | `force_push` | Use force push | No | `true` |
-| `dry_run` | Log actions without pushing | No | `false` |
+| `dry_run` | Dry run mode with remote pre-check | No | `false` |
+| `retry_count` | Number of retry attempts on push failure | No | `0` |
+| `retry_delay` | Delay in seconds between retries | No | `5` |
+| `exclude_branches` | Branches to exclude (comma-separated) | No | `''` |
+| `parallel` | Mirror to targets in parallel | No | `false` |
 | `debug` | Enable debug logging | No | `false` |
 
 <br/>
@@ -219,7 +227,8 @@ Many teams need to keep repository mirrors in sync across multiple Git providers
 │   │   ├── config.go            # Configuration loading & target parsing
 │   │   └── config_test.go       # Config tests
 │   ├── mirror/
-│   │   ├── mirror.go            # Mirror logic & auth URL injection
+│   │   ├── mirror.go            # Mirror logic, retry, parallel, auth URL injection
+│   │   ├── ssh.go               # SSH key setup/cleanup
 │   │   └── mirror_test.go       # Mirror tests
 │   └── output/
 │       └── output.go            # GitHub Actions output writer

docs/AUTHENTICATION.md

@@ -1,6 +1,6 @@
 # Authentication
 
-Guide for configuring authentication for each supported Git provider.
+Guide for configuring authentication for each supported Git provider, including step-by-step token creation instructions.
 
 <br/>
 
@@ -11,6 +11,7 @@ Guide for configuring authentication for each supported Git provider.
 - [Bitbucket](#bitbucket)
 - [AWS CodeCommit](#aws-codecommit)
 - [SSH Key](#ssh-key)
+- [Adding Secrets to GitHub Actions](#adding-secrets-to-github-actions)
 - [Security Best Practices](#security-best-practices)
 
 <br/>
@@ -27,16 +28,42 @@ Uses OAuth2 token authentication. The token is injected into the HTTPS URL as `h
     gitlab_token: ${{ secrets.GITLAB_TOKEN }}
 ```
 
+<br/>
+
 ### Required Token Scopes
 
-- `write_repository` — Push access to the target repository
-- `read_repository` — (optional) If the target repo is private
+| Scope | Purpose | Required |
+|-------|---------|----------|
+| `write_repository` | Push access to the target repository | Yes |
+| `read_repository` | Read access (for private repos) | Optional |
+
+<br/>
+
+### Step-by-Step: Creating a GitLab Personal Access Token
+
+1. Log in to [GitLab](https://gitlab.com)
+2. Click your **avatar** (top-right) → **Preferences**
+3. In the left sidebar, click **Access Tokens**
+4. Click **Add new token**
+5. Configure:
+   - **Token name**: `git-mirror-action`
+   - **Expiration date**: Set an appropriate date (recommended: 1 year max)
+   - **Scopes**: Check `write_repository`
+6. Click **Create personal access token**
+7. **Copy the token immediately** — it will not be shown again
+8. Add it as a GitHub secret named `GITLAB_TOKEN` ([how to add secrets](#adding-secrets-to-github-actions))
+
+<br/>
+
+### Alternative: GitLab Project Access Token
+
+For organization-level access, use a Project Access Token instead:
 
-### Creating a GitLab Token
+1. Go to your **GitLab project** → **Settings** → **Access Tokens**
+2. Create a token with `write_repository` scope and **Maintainer** role
+3. Use the token the same way as a personal access token
 
-1. Go to **GitLab** > **Settings** > **Access Tokens**
-2. Create a token with `write_repository` scope
-3. Add the token as a GitHub secret (`GITLAB_TOKEN`)
+> **Note**: Project Access Tokens are available on GitLab Premium and higher. Free tier users should use Personal Access Tokens.
 
 <br/>
 
@@ -52,11 +79,45 @@ Uses x-access-token authentication. The token is injected as `https://x-access-t
     github_token: ${{ secrets.MIRROR_GITHUB_TOKEN }}
 ```
 
+<br/>
+
 ### Required Token Scopes
 
-- `repo` — Full control of private repositories (or `public_repo` for public repos)
+| Scope | Purpose | Required |
+|-------|---------|----------|
+| `repo` | Full control of private repositories | Yes (private repos) |
+| `public_repo` | Push to public repositories only | Yes (public repos) |
+
+> **Important**: Do NOT use `${{ secrets.GITHUB_TOKEN }}` for cross-repository mirroring. It only has access to the current repository. Use a Personal Access Token (PAT) instead.
+
+<br/>
+
+### Step-by-Step: Creating a GitHub Fine-Grained PAT (Recommended)
+
+1. Log in to [GitHub](https://github.com)
+2. Click your **avatar** (top-right) → **Settings**
+3. Scroll down in the left sidebar → **Developer settings**
+4. Click **Personal access tokens** → **Fine-grained tokens**
+5. Click **Generate new token**
+6. Configure:
+   - **Token name**: `git-mirror-action`
+   - **Expiration**: Select an appropriate duration
+   - **Resource owner**: Select the target organization or your account
+   - **Repository access**: Select **Only select repositories** → choose the target repo
+   - **Permissions** → **Repository permissions**:
+     - **Contents**: `Read and write`
+7. Click **Generate token**
+8. **Copy the token immediately**
+9. Add it as a GitHub secret named `MIRROR_GITHUB_TOKEN`
+
+<br/>
 
-> **Note**: Do not use `${{ secrets.GITHUB_TOKEN }}` for cross-repository mirroring. It only has access to the current repository. Use a Personal Access Token (PAT) instead.
+### Alternative: Classic PAT
+
+1. Go to **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)**
+2. Click **Generate new token (classic)**
+3. Check `repo` scope (or `public_repo` for public repos only)
+4. Generate and copy the token
 
 <br/>
 
@@ -73,30 +134,47 @@ Uses username and app password authentication. Credentials are injected as `http
     bitbucket_password: ${{ secrets.BITBUCKET_APP_PASSWORD }}
 ```
 
-### Creating a Bitbucket App Password
+<br/>
+
+### Required Permissions
 
-1. Go to **Bitbucket** > **Personal settings** > **App passwords**
-2. Create a password with **Repositories: Write** permission
-3. Add the username and app password as GitHub secrets
+| Permission | Purpose | Required |
+|------------|---------|----------|
+| Repositories: Write | Push access to repositories | Yes |
+| Repositories: Read | Read access (for private repos) | Optional |
 
 > **Note**: Both `bitbucket_username` and `bitbucket_password` must be provided. If either is missing, the URL is used as-is.
 
 <br/>
 
-## AWS CodeCommit
+### Step-by-Step: Creating a Bitbucket App Password
+
+1. Log in to [Bitbucket](https://bitbucket.org)
+2. Click your **avatar** (bottom-left) → **Personal settings**
+3. In the left sidebar under **Access management**, click **App passwords**
+4. Click **Create app password**
+5. Configure:
+   - **Label**: `git-mirror-action`
+   - **Permissions**: Check **Repositories** → **Write** (this also grants Read)
+6. Click **Create**
+7. **Copy the password immediately** — it will not be shown again
+8. Add two GitHub secrets:
+   - `BITBUCKET_USERNAME`: Your Bitbucket username (not email)
+   - `BITBUCKET_APP_PASSWORD`: The app password you just created
 
-CodeCommit uses IAM-based authentication via the Git credential helper. The URL is used as-is without token injection.
+<br/>
 
-```yaml
-- uses: somaz94/git-mirror-action@v1
-  with:
-    targets: |
-      codecommit::https://git-codecommit.us-east-1.amazonaws.com/v1/repos/myrepo
-```
+### Finding Your Bitbucket Username
 
-### IAM Configuration
+Your Bitbucket username is NOT your email. To find it:
+1. Go to **Personal settings**
+2. Your username is shown under **Atlassian account settings** or in the URL: `bitbucket.org/<username>/`
 
-Ensure the runner has AWS credentials configured with `codecommit:GitPush` permissions. For GitHub Actions, use `aws-actions/configure-aws-credentials`:
+<br/>
+
+## AWS CodeCommit
+
+CodeCommit uses IAM-based authentication via the Git credential helper. The URL is used as-is without token injection.
 
 ```yaml
 - name: Configure AWS credentials
@@ -117,6 +195,60 @@ Ensure the runner has AWS credentials configured with `codecommit:GitPush` permi
 
 <br/>
 
+### Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "codecommit:GitPush",
+        "codecommit:CreateBranch",
+        "codecommit:GetRepository"
+      ],
+      "Resource": "arn:aws:codecommit:us-east-1:123456789012:myrepo"
+    }
+  ]
+}
+```
+
+<br/>
+
+### Step-by-Step: Creating AWS IAM Credentials
+
+#### Option A: IAM User with Access Keys
+
+1. Log in to [AWS Console](https://console.aws.amazon.com) → **IAM**
+2. Click **Users** → **Create user**
+3. Enter username: `git-mirror-action`
+4. Click **Next** → **Attach policies directly**
+5. Click **Create policy** and paste the JSON above (adjust the Resource ARN)
+6. Attach the policy to the user
+7. Go to the user → **Security credentials** → **Create access key**
+8. Select **Third-party service** → **Create access key**
+9. **Copy both keys immediately**
+10. Add two GitHub secrets:
+    - `AWS_ACCESS_KEY_ID`: The access key ID
+    - `AWS_SECRET_ACCESS_KEY`: The secret access key
+
+#### Option B: OIDC (Recommended for Production)
+
+For keyless authentication, use GitHub OIDC provider:
+
+```yaml
+- name: Configure AWS credentials (OIDC)
+  uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: arn:aws:iam::123456789012:role/git-mirror-role
+    aws-region: us-east-1
+```
+
+See [AWS docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) for OIDC setup.
+
+<br/>
+
 ## SSH Key
 
 For providers that support SSH, use the `ssh_private_key` input with the `generic` provider.
@@ -129,6 +261,8 @@ For providers that support SSH, use the `ssh_private_key` input with the `generi
     ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
 ```
 
+<br/>
+
 ### How It Works
 
 When `ssh_private_key` is provided, the action automatically:
@@ -138,11 +272,78 @@ When `ssh_private_key` is provided, the action automatically:
 3. Sets `GIT_SSH_COMMAND` to use the configured key
 4. Cleans up all SSH files after mirroring completes
 
-### Setup
+<br/>
+
+### Step-by-Step: Creating an SSH Key Pair
+
+1. Generate an Ed25519 key pair (no passphrase):
+
+   ```bash
+   ssh-keygen -t ed25519 -C "git-mirror-action" -f mirror_key -N ""
+   ```
+
+2. This creates two files:
+   - `mirror_key` — Private key (add to GitHub secrets)
+   - `mirror_key.pub` — Public key (add to target Git server)
 
-1. Generate an SSH key pair: `ssh-keygen -t ed25519 -C "mirror-action"`
-2. Add the public key to the target Git server
-3. Add the private key as a GitHub secret (`SSH_PRIVATE_KEY`)
+3. **Add the public key** to the target Git server:
+   - **GitLab**: Settings → Repository → Deploy keys → Add key (check "Grant write permissions")
+   - **GitHub**: Settings → Deploy keys → Add deploy key (check "Allow write access")
+   - **Bitbucket**: Repository settings → Access keys → Add key
+   - **Custom server**: Add to `~/.ssh/authorized_keys` on the server
+
+4. **Add the private key** as a GitHub secret:
+   ```bash
+   # Copy the private key content
+   cat mirror_key
+   ```
+   Add this as `SSH_PRIVATE_KEY` in GitHub secrets
+
+5. **Delete local key files** after setup:
+   ```bash
+   rm mirror_key mirror_key.pub
+   ```
+
+<br/>
+
+## Adding Secrets to GitHub Actions
+
+All credentials must be stored as GitHub secrets. Never hardcode them in workflow files.
+
+<br/>
+
+### Step-by-Step: Adding a Repository Secret
+
+1. Go to your **GitHub repository**
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Enter:
+   - **Name**: The secret name (e.g., `GITLAB_TOKEN`)
+   - **Secret**: The token/password value
+5. Click **Add secret**
+
+<br/>
+
+### Step-by-Step: Adding an Organization Secret
+
+1. Go to your **GitHub organization**
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New organization secret**
+4. Enter the name and value
+5. Under **Repository access**, select which repos can use this secret
+6. Click **Add secret**
+
+<br/>
+
+### Quick Reference: Required Secrets Per Provider
+
+| Provider | Secrets Needed |
+|----------|---------------|
+| GitLab | `GITLAB_TOKEN` |
+| GitHub | `MIRROR_GITHUB_TOKEN` |
+| Bitbucket | `BITBUCKET_USERNAME`, `BITBUCKET_APP_PASSWORD` |
+| CodeCommit | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` |
+| SSH | `SSH_PRIVATE_KEY` |
 
 <br/>
 
@@ -153,10 +354,14 @@ When `ssh_private_key` is provided, the action automatically:
 - **Rotate tokens regularly** — Set expiration dates and rotate periodically
 - **Use separate tokens per target** — Avoid reusing a single token across providers
 - **Audit access** — Regularly review which tokens have access to your repositories
+- **Prefer fine-grained tokens** — GitHub Fine-Grained PATs and GitLab Project Access Tokens over classic tokens
+- **Use OIDC where possible** — For AWS CodeCommit, prefer OIDC over static access keys
+
+<br/>
 
 ### Built-in Security Features
 
 - **Credential URL encoding** — Special characters (`@`, `:`, `/`, etc.) in passwords are URL-encoded to prevent URL parsing issues
-- **Debug log masking** — Tokens and passwords are replaced with `***` in debug logs
+- **Log masking** — Tokens, passwords, and usernames are replaced with `***` in all log output (including git stderr)
 - **SSH key cleanup** — SSH key files are automatically removed after mirroring
 - **Config validation** — Warns when required credentials are missing for a target provider