Backup n8n Workflows to a Gitea Repository

Learn how to automatically back up your n8n workflows to a Gitea Git repository. This guide walks through a reusable workflow that fetches workflows, encodes them, checks for changes, and safely creates or updates files in Gitea on a schedule.

Why back up n8n workflows to Gitea?

Workflows are the heart of any automation platform. Backing them up provides:

• Versioned history of changes
• Easy recovery after accidental edits or system failures
• Collaboration and auditability via Git
• Offsite storage on managed Git servers like Gitea

Solution overview

This solution uses an n8n workflow template that:

• Runs on a schedule (e.g., every 45 minutes)
• Retrieves all workflows from n8n via API
• Iterates over each workflow and prepares a JSON file
• Base64-encodes the workflow content (as required by Git/Gitea API)
• Checks if a file exists for the workflow in the configured Gitea repo
• Creates a new file or updates the existing one only when there are changes

What you need

• An n8n instance with API access
• A Gitea instance (self-hosted or managed)
• A Gitea repository to store workflow JSON files
• An access token for Gitea with repo read/write permissions

Step-by-step setup

1. Configure global variables

Open the Globals (Set) node in the template and set:

• repo.url — your Gitea base URL (e.g., https://git.example.com)
• repo.owner — the owner or organization that owns the repo
• repo.name — the repository name (for example workflows)

2. Create a Gitea personal access token

In Gitea: Settings → Applications → Generate Token. Grant repository read/write permission. Copy the token.

In n8n credentials manager, create a credential (HTTP Header Auth) named for example Gitea Token. For the header name use Authorization and for value use Bearer YOUR_PERSONAL_ACCESS_TOKEN. Note: include the space after Bearer.

3. Connect credentials to HTTP request nodes

Assign the Gitea token credential to the three HTTP request nodes that interact with Gitea in the workflow:

• GetGitea — reads an existing file from the repo
• PostGitea — creates a new file
• PutGitea — updates an existing file (requires file SHA)

4. Ensure the workflow fetch node has API credentials

The node that retrieves workflows from n8n must have valid API authentication (API key or Basic Auth) so it can list workflows. Test it manually to confirm it returns all workflows.

5. How the template handles files

Each workflow is converted to a pretty-printed JSON string and then base64-encoded. The Git/Gitea API expects the file content encoded in base64 when creating/updating via the REST API.

Filename convention used by the workflow: <workflow-name>.json. If your workflow names are not unique, consider appending the workflow ID to ensure uniqueness.

6. Check file existence and changes

The template calls the Gitea /api/v1/repos/{owner}/{repo}/contents/{path} endpoint to check whether the file exists. If it does, the node returns a SHA for the current file and the content (base64-decoded) so the workflow can compare the current repository content with the local workflow JSON.

If the content differs, the workflow updates the file using a PUT request including the existing file SHA. If the file does not exist (404), the template will create it using a POST request (or PUT depending on your API flavor).

Key implementation details (useful snippets)

Gitea API endpoints

• Get file: GET /api/v1/repos/{owner}/{repo}/contents/{path}
• Create file: POST /api/v1/repos/{owner}/{repo}/contents/{path} (or PUT depending on version)
• Update file: PUT /api/v1/repos/{owner}/{repo}/contents/{path} (include sha of the file)

Authorization header

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Example body for creating/updating a file

{
  "content": "BASE64_ENCODED_FILE_CONTENT",
  "message": "Backup: update workflow <name>",
  "sha": "EXISTING_FILE_SHA"  // only for updates
}

Best practices and security

• Rotate the Gitea token periodically and store it securely (n8n credentials or a secrets manager).
• Limit token scope to the specific repository when possible.
• Consider storing workflow backups in a protected repo or an organization with restricted access.
• Include commit messages that make it easy to identify changes (timestamp, actor, summary).
• Monitor the scheduled job for failures and configure n8n alerts or logging.

Troubleshooting

404 when checking a file

A 404 response from the GetGitea node usually means the file doesn’t exist — this is expected for new workflows. The template handles this and creates the file automatically.

401/403 authorization errors

Verify the token is correct and that the Authorization header has the format Bearer YOUR_TOKEN. Ensure the token has repo write permission for the target repository.

File not updating

• Confirm the workflow computes the correct SHA and includes it in the update request.
• Check that the change detection compares the repository content (decoded) with the local workflow JSON before sending updates.

Activate and test

1) Run the workflow manually to ensure it reads workflows and performs create/update operations successfully. 2) Check the repository for the newly created JSON files. 3) Enable the schedule trigger to automate backups.

Conclusion

Backing up n8n workflows to a Gitea repository adds version control, safety, and portability to your automation platform. The provided n8n template handles encoding, existence checks, and safe create/update operations so you can automate backups and focus on building automations.

Next steps: Import the template into your n8n instance, configure the Globals and credentials, run the workflow, and verify the repository. If you need help, reach out to the n8n community or your internal DevOps team.

Call to action: Import this template now, run it manually to validate, then enable the schedule to protect your workflows automatically. Share feedback or issues on the forum so others can benefit.