{"id":46039957,"url":"https://github.com/automations-project/n8n-data-manager","last_synced_at":"2026-03-01T06:11:10.625Z","repository":{"id":300011713,"uuid":"976159113","full_name":"Automations-Project/n8n-data-manager","owner":"Automations-Project","description":"A robust shell script for automated backup and restore of n8n workflows, credentials, and environment variables to GitHub. Supports interactive and non-interactive modes, Alpine and Ubuntu containers, and includes comprehensive error handling.","archived":false,"fork":false,"pushed_at":"2025-06-19T12:19:58.000Z","size":1307,"stargazers_count":22,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-19T12:35:13.727Z","etag":null,"topics":["alpine-compatible","bash-automation","data-management","devops-automation","docker-backup","github-backup","n8n-automation","n8n-backup","n8n-restore","self-hosted-backup","shell-script","workflow-backup","workflow-management"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Automations-Project.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-01T15:52:24.000Z","updated_at":"2025-06-19T12:19:53.000Z","dependencies_parsed_at":"2025-06-19T12:47:29.836Z","dependency_job_id":null,"html_url":"https://github.com/Automations-Project/n8n-data-manager","commit_stats":null,"previous_names":["automations-project/n8n-data-manager"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Automations-Project/n8n-data-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automations-Project%2Fn8n-data-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automations-Project%2Fn8n-data-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automations-Project%2Fn8n-data-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automations-Project%2Fn8n-data-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Automations-Project","download_url":"https://codeload.github.com/Automations-Project/n8n-data-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Automations-Project%2Fn8n-data-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29962004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine-compatible","bash-automation","data-management","devops-automation","docker-backup","github-backup","n8n-automation","n8n-backup","n8n-restore","self-hosted-backup","shell-script","workflow-backup","workflow-management"],"created_at":"2026-03-01T06:11:10.012Z","updated_at":"2026-03-01T06:11:10.614Z","avatar_url":"https://github.com/Automations-Project.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# n8n-manager: Backup \u0026 Restore for n8n Docker via GitHub\n\u003c!-- ALL_BADGES_START --\u003e\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Automations-Project/n8n-data-manager/ci.yml?branch=main\u0026style=flat-square)](https://github.com/Automations-Project/n8n-data-manager/actions/workflows/ci.yml) [![Latest Release](https://img.shields.io/github/v/release/Automations-Project/n8n-data-manager?include_prereleases\u0026style=flat-square\u0026label=release)](https://github.com/Automations-Project/n8n-data-manager/releases/latest) [![ShellCheck](https://img.shields.io/badge/ShellCheck-passing-brightgreen?style=flat-square)](https://github.com/Automations-Project/n8n-data-manager/actions/workflows/ci.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/Automations-Project/n8n-data-manager?style=flat-square\u0026logo=github)](https://github.com/Automations-Project/n8n-data-manager/stargazers) [![GitHub Forks](https://img.shields.io/github/forks/Automations-Project/n8n-data-manager?style=flat-square\u0026logo=github)](https://github.com/Automations-Project/n8n-data-manager/network/members) [![Contributors](https://img.shields.io/github/contributors/Automations-Project/n8n-data-manager?style=flat-square)](https://github.com/Automations-Project/n8n-data-manager/graphs/contributors) [![Open Issues](https://img.shields.io/github/issues-raw/Automations-Project/n8n-data-manager?style=flat-square\u0026logo=github)](https://github.com/Automations-Project/n8n-data-manager/issues)\n[![Last Commit](https://img.shields.io/github/last-commit/Automations-Project/n8n-data-manager/main?style=flat-square)](https://github.com/Automations-Project/n8n-data-manager/commits/main) [![Repo Size](https://img.shields.io/github/repo-size/Automations-Project/n8n-data-manager?style=flat-square)](https://github.com/Automations-Project/n8n-data-manager) [![Project Status: Active](https://img.shields.io/badge/status-active-success.svg?style=flat-square)](./#)\n[![GitHub Top Language](https://img.shields.io/github/languages/top/Automations-Project/n8n-data-manager?style=flat-square)](https://github.com/Automations-Project/n8n-data-manager) [![Maintenance Status](https://img.shields.io/badge/Maintenance-Actively%20Maintained-green.svg?style=flat-square)](./#) \n\u003c!-- ALL_BADGES_END --\u003e\n\n![Banner](.github/images/Banner.png)\n\n`n8n-manager` is a robust command-line tool designed to simplify the backup and restore process for your [n8n](https://n8n.io/) instances running in Docker containers. It leverages Git and GitHub to securely store and manage your n8n workflows, credentials, and environment variables.\n\nThis script provides both interactive and non-interactive modes, making it suitable for manual use and automation/CI/CD pipelines.\n\n## ✨ Features\n\n*   **Interactive Mode:** User-friendly menus guide you through selecting containers and actions.\n*   **Non-Interactive Mode:** Fully automatable via command-line arguments, perfect for scripting.\n*   **GitHub Integration:** Backs up n8n data (workflows, credentials, environment variables) to a private or public GitHub repository.\n*   **Backup Options:**\n    *   **Standard Backup:** Overwrites the latest backup files on the specified branch.\n    *   **Dated Backups (`--dated`):** Creates timestamped subdirectories (e.g., `backup_YYYY-MM-DD_HH-MM-SS/`) for each backup, preserving history.\n*   **Restore Options:**\n    *   **Full Restore:** Restores both workflows and credentials.\n    *   **Selective Restore (`--restore-type`):** Restore only `workflows` or only `credentials`.\n*   **Container Compatibility:**\n    *   **Alpine Support:** Fully compatible with n8n containers based on Alpine Linux.\n    *   **Ubuntu Support:** Works seamlessly with containers based on Ubuntu/Debian.\n*   **Safety First:**\n    *   **Pre-Restore Backup:** Automatically creates a temporary local backup of current data before starting a restore.\n    *   **Automatic Rollback:** If the restore process fails, the script attempts to automatically roll back to the pre-restore state.\n    *   **GitHub Pre-Checks:** Verifies GitHub token validity, required scopes (`repo`), repository existence, and branch existence (for restore) before proceeding.\n    *   **Dry Run Mode (`--dry-run`):** Simulate backup or restore operations without making any actual changes to your n8n instance or GitHub repository.\n*   **Robust Error Handling:**\n    *   **Shell-Safe Operations:** All operations use explicit string comparisons and proper error checks to avoid common shell pitfalls.\n    *   **Descriptive Error Messages:** Clear error messaging with specific details about what went wrong.\n    *   **Improved File Validation:** Smart checks ensure n8n files are valid before attempting import operations.\n*   **Configuration File:** Store default settings (token, repo, container, etc.) in `~/.config/n8n-manager/config` for convenience.\n*   **Enhanced Logging:**\n    *   Clear, colored output for interactive use.\n    *   Verbose/Debug mode (`--verbose`) for detailed troubleshooting.\n    *   Option to log all output to a file (`--log-file`).\n    *   Trace mode (`--trace`) for in-depth debugging.\n*   **Dependency Checks:** Verifies required tools (Docker, Git, curl) are installed on the host.\n*   **Container Detection:** Automatically detects running n8n containers.\n\n## 📋 Prerequisites\n\n*   **Host Machine:**\n    *   Linux environment (tested on Ubuntu, should work on most distributions).\n    *   `docker`: To interact with the n8n container.\n    *   `git`: To interact with the GitHub repository.\n    *   `curl`: To perform GitHub API pre-checks.\n    *   `bash`: The script interpreter.\n*   **n8n Container:**\n    *   Must be running.\n    *   Must be based on an official n8n image (or include the `n8n` CLI tool).\n    *   The `git` command is *not* required inside the container.\n*   **GitHub:**\n    *   A GitHub account.\n    *   A GitHub repository (private recommended) to store the backups.\n    *   A [GitHub Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `repo` scope enabled. This scope is necessary to access repositories (both public and private) and push changes.\n\n## 🚀 Installation\n\nYou can install `n8n-manager` using the provided installation script. This will download the main script and place it in `/usr/local/bin` for easy system-wide access.\n\n**Note:** You need `curl` and `sudo` (or run as root) for the installation.\n\n```bash\ncurl -sSL -L https://i.n8n.community | sudo bash\n```\n\nAlternatively, you can download the `n8n-manager.sh` script manually, make it executable (`chmod +x n8n-manager.sh`), and run it directly (`./n8n-manager.sh`) or place it in your desired `$PATH` directory.\n\n## ⚙️ Configuration File (Optional)\n\nFor convenience, you can create a configuration file to store default settings. The script looks for this file at `~/.config/n8n-manager/config` by default. You can specify a different path using the `--config` argument.\n\nCreate the directory if it doesn't exist:\n\n```bash\nmkdir -p ~/.config/n8n-manager\n```\n\nCreate the file `~/.config/n8n-manager/config` with content like this:\n\n```ini\n# GitHub Personal Access Token (Required)\nCONF_GITHUB_TOKEN=\"ghp_YourGitHubPATGoesHere\"\n\n# GitHub Repository (Required, format: username/repo)\nCONF_GITHUB_REPO=\"your-github-username/n8n-backups\"\n\n# Default GitHub Branch (Optional, defaults to main)\nCONF_GITHUB_BRANCH=\"main\"\n\n# Default n8n Container Name or ID (Optional)\nCONF_DEFAULT_CONTAINER=\"my-n8n-container\"\n\n# Use Dated Backups by default (Optional, true/false, defaults to false)\nCONF_DATED_BACKUPS=true\n\n# Default Restore Type (Optional, all/workflows/credentials, defaults to all)\nCONF_RESTORE_TYPE=\"all\"\n\n# Enable Verbose Logging by default (Optional, true/false, defaults to false)\nCONF_VERBOSE=false\n\n# Log output to a file (Optional, must be an absolute path)\nCONF_LOG_FILE=\"/var/log/n8n-manager.log\"\n```\n\n**Security Note:** Ensure the configuration file has appropriate permissions (e.g., `chmod 600 ~/.config/n8n-manager/config`) as it contains your GitHub PAT.\n\nCommand-line arguments always override settings from the configuration file.\n\n## 💡 Usage\n\n### Interactive Mode\n\nSimply run the script without any arguments (or only optional ones like `--verbose`):\n\n```bash\nn8n-manager.sh\n```\n\nThe script will guide you through:\n1.  Selecting the action (Backup/Restore).\n2.  Selecting the target n8n container.\n3.  Entering GitHub details (Token, Repo, Branch) if not found in the config file or provided via arguments.\n4.  Confirming potentially destructive actions (like restore).\n\n### Non-Interactive Mode\n\nProvide all required parameters via command-line arguments. This is ideal for automation (e.g., cron jobs).\n\n```bash\nn8n-manager.sh --action \u003caction\u003e --container \u003cid|name\u003e --token \u003cpat\u003e --repo \u003cuser/repo\u003e [OPTIONS]\n```\n\n**Required Arguments for Non-Interactive Use:**\n\n*   `--action \u003caction\u003e`: `backup` or `restore`.\n*   `--container \u003cid|name\u003e`: The name or ID of the running n8n Docker container.\n*   `--token \u003cpat\u003e`: Your GitHub PAT.\n*   `--repo \u003cuser/repo\u003e`: Your GitHub repository.\n\n**Optional Arguments:**\n\n*   `--branch \u003cbranch\u003e`: GitHub branch to use (defaults to `main`).\n*   `--dated`: (Backup only) Create a timestamped subdirectory for the backup.\n*   `--restore-type \u003ctype\u003e`: (Restore only) Choose what to restore: `all` (default), `workflows`, or `credentials`.\n*   `--dry-run`: Simulate the action without making changes.\n*   `--verbose`: Enable detailed debug logging for troubleshooting.\n*   `--trace`: Enable in-depth script debugging with bash execution trace.\n*   `--log-file \u003cpath\u003e`: Append all logs (plain text) to the specified file.\n*   `--config \u003cpath\u003e`: Use a custom configuration file path.\n*   `-h`, `--help`: Show the help message.\n\n**Example: Non-Interactive Backup**\n\n```bash\nn8n-manager.sh \\\n  --action backup \\\n  --container my-n8n-container \\\n  --token \"ghp_YourToken\" \\\n  --repo \"myuser/my-n8n-backup\" \\\n  --branch main \\\n  --dated \\\n  --log-file /var/log/n8n-backup.log\n```\n\n**Example: Non-Interactive Restore (Workflows Only)**\n\n```bash\nn8n-manager.sh \\\n  --action restore \\\n  --container my-n8n-container \\\n  --token \"ghp_YourToken\" \\\n  --repo \"myuser/my-n8n-backup\" \\\n  --branch main \\\n  --restore-type workflows\n```\n\n## 🔄 Backup \u0026 Restore Process\n\n### Backup\n\n1.  **Connect:** Establishes connection parameters (container, GitHub details).\n2.  **Pre-Checks:** Verifies GitHub token, scopes, and repository access.\n3.  **Git Prep:** Clones or fetches the specified branch into a temporary directory.\n4.  **Export:** Executes `n8n export:workflow` and `n8n export:credentials` inside the container.\n5.  **Environment:** Captures `N8N_` environment variables from the container.\n6.  **Copy:** Copies exported `workflows.json`, `credentials.json`, and `.env` files to the temporary Git directory (optionally into a dated subdirectory).\n7.  **Commit:** Commits the changes with a descriptive message including the n8n version and timestamp.\n8.  **Push:** Pushes the commit to the specified GitHub repository and branch.\n9.  **Cleanup:** Removes temporary files and directories.\n\n### Restore\n\n1.  **Connect:** Establishes connection parameters.\n2.  **Pre-Checks:** Verifies GitHub token, scopes, repository, and *branch* access.\n3.  **Confirmation:** Prompts the user for confirmation in interactive mode.\n4.  **Pre-Restore Backup:** Exports current workflows and credentials from the container to a temporary local directory (for rollback).\n5.  **Fetch:** Clones the specified branch from the GitHub repository.\n6.  **Copy to Container:** Copies the `workflows.json` and/or `credentials.json` from the cloned repo to the container.\n7.  **Import:** Executes `n8n import:workflow` and/or `n8n import:credentials` inside the container.\n8.  **Cleanup:** Removes temporary files and directories.\n9.  **Rollback (on failure):** If any step after the pre-restore backup fails, the script attempts to import the backed-up data back into n8n.\n\n## ⚠️ Error Handling \u0026 Rollback\n\nThe script includes error trapping (`set -Eeuo pipefail`) and specific checks at various stages. Version 3.0+ includes significantly improved error handling specifically designed to address common issues in shell scripting:\n\n- **Explicit String Comparisons**: Boolean variables and conditions now use explicit string comparisons (e.g., `[ \"$variable\" = \"true\" ]`) to avoid empty command errors.\n- **Proper Return Values**: All functions have proper return values to avoid the \"command not found\" errors that occur with empty returns.\n- **Robust Git Operations**: Git operations have been restructured to use proper error handling and to verify commands succeed at each step.\n- **Alpine Container Compatibility**: Special handling for file operations in Alpine-based containers ensures compatibility regardless of container OS.\n\n## 🔧 Container Compatibility\n\nVersion 3.0.5 includes specific improvements for working with different container environments:\n\n### Alpine Linux Containers\n\nOlder versions of the script sometimes ran into issues with Alpine-based containers due to differences in shell behavior and file permissions. The latest version includes:\n\n- Use of the `ash` shell for Alpine-specific commands\n- More robust file existence checks before operations\n- Proper handling of temporary files\n- Intelligent error suppression for non-critical operations\n\n### Best Practices for Both Container Types\n\nFor optimal performance with both Alpine and Ubuntu/Debian containers:\n\n- Ensure the n8n CLI tool is available in the container\n- Check that Docker permissions are sufficient on the host machine\n- Consider using a named volume for n8n persistent data\n\n## 📜 Logging\n\n*   **Standard Output:** Provides colored, user-friendly status messages.\n*   **Verbose Mode (`--verbose`):** Prints detailed debug information, including internal steps and command outputs.\n*   **Log File (`--log-file \u003cpath\u003e`):** Appends plain-text, timestamped logs to the specified file, suitable for auditing or background processes.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to open issues on the GitHub repository.\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomations-project%2Fn8n-data-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautomations-project%2Fn8n-data-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomations-project%2Fn8n-data-manager/lists"}