You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Here are some key observations to aid the review process:
⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪
🧪 No relevant tests
🔒 Security concerns
Sensitive information exposure: The documentation includes examples where secrets (e.g., TYK_DASHBOARD_SECRET, AWS_SECRET_ACCESS_KEY) are used. Ensure that users are adequately warned about securely managing these secrets and not exposing them in version control or logs.
Ensure that all commands, flags, and examples provided in the documentation are accurate and up-to-date, especially for Tyk Sync commands and GitHub Actions workflows.
---title: "Synchronize Tyk Environment With GitHub using Tyk Sync"date: 2025-01-10tags: ["Tyk API Management", "Tyk Sync", "Tyk Operator", "Github", "Kubernetes", "Automations"]description: How to synchronize Tyk configuration with Github using Tyk Synckeywords: ["Tyk API Management", "Tyk Sync", "Tyk Operator", "Github", "Kubernetes", "Automations"]aliases:
- /advanced-configuration/manage-multiple-environments/tyk-sync
- /product-stack/tyk-sync/commands/sync-dump
- /product-stack/tyk-sync/commands/sync-examples
- /product-stack/tyk-sync/commands/sync-publish
- /product-stack/tyk-sync/commands/sync-sync
- /product-stack/tyk-sync/commands/sync-update
- /product-stack/tyk-sync/installing-tyk-sync
- /product-stack/tyk-sync/overview
- /product-stack/tyk-sync/tutorials/tutorial-backup-api-configurations
- /product-stack/tyk-sync/tutorials/tutorial-synchronise-api-configurations
- /product-stack/tyk-sync/tutorials/tutorial-update-api-configurations
- /tyk-sync---## Introduction
Tyk Sync enables you to export and import Tyk configurations directly from Git, keeping environments aligned without manual configuration updates. This section covers the setup and use of Tyk Sync, providing steps to ensure consistent configurations across different environments.
## Tyk Sync Features
Tyk Sync works with *Tyk Dashboard* installation. With Tyk Dashboard, Tyk Sync supports managing API definitions, security policies, and API templates.
| Tyk Sync Feature | Tyk Dashboard (Licensed) || ---------------------------------------------------------------------------|--------------------------|| <h4>Backup objects from Tyk to a directory</h4>If you want to backup your API definitions, policies and templates in Tyk, you can use the `dump` command. It allows you to save the objects in transportable files. You can use this command to backup important API configurations before upgrading Tyk, or to save API configurations from one Dashboard instance and then use `update`, `publish`, or `sync` commands to update the API configurations to another Dashboard instance. | ✅ || <h4>Synchronise objects from Git (or any VCS) to Tyk</h4>To implement GitOps for API management, store your API definitions, policies and templates in Git or any version control system. Use the `sync` command to synchronise those objects to Tyk. During this operation, Tyk Sync will delete any objects in the Dashboard that cannot be found in the VCS, and update those that can be found and create those that are missing. | ✅ || <h4>Update objects</h4>The `update` command will read from VCS or file system and will attempt to identify matching API definitions, policies and templates in the target Dashboard, and update them. Unmatched objects will not be created. | ✅ || <h4>Publish objects</h4>The `publish` command will read from VCS or file system and create API definitions, policies, and templates in target Dashboard. This will not update any existing objects. If it detects a collision, the command will stop. | ✅ || <h4>Show and import Tyk examples</h4>The `examples` command allow you to show and import [Tyk examples](https://github.com/TykTechnologies/tyk-examples). An easy way to load up your Tyk installation with some interesting examples!| ✅ |**Working with OAS APIs**
Starting with Sync v1.5+ and Dashboard v5.3.2+, Tyk Sync supports both [Tyk OAS APIs]({{<ref "getting-started/key-concepts/high-level-concepts">}}) and [Tyk Classic APIs]({{<ref "getting-started/key-concepts/what-is-an-api-definition#api-definition-types">}}) when working with the Tyk Dashboard, without requiring special flags or configurations.
For Sync versions v1.4.1 to v1.4.3, enabling Tyk Sync for Tyk OAS APIs requires the [allow-unsafe-oas]({{<ref "tyk-dashboard/configuration#allow_unsafe_oas">}}) configuration in the Dashboard, along with the `--allow-unsafe-oas` flag when invoking Tyk Sync. Note that Tyk Sync versions v1.4.1 to 1.4.3 do not support API Category for Tyk OAS APIs.
**Working with Tyk Streams APIs**
Tyk Streams API support was introduced in Tyk Dashboard v5.7.0. Tyk Sync v2.0 and later is compatible with Tyk Streams APIs and manages them similarly to Tyk OAS APIs. With Tyk Sync, you can seamlessly sync, publish, update, and dump Tyk Streams APIs just like OAS APIs.
Note: The Streams API validator is not applied during these operations.
**Working with Open Source Gateway**
From Sync v2.0, compatibility with the Open Source Tyk Gateway has been removed, making Tyk Sync v2.0 compatible exclusively with licensed Tyk Dashboard. As a result, Tyk Sync is no longer usable with the Open Source (OSS) version of the Tyk Gateway.
## Set up Tyk Sync### Installation
Currently the application is available via [Docker](https://hub.docker.com/r/tykio/tyk-sync) and [Packagecloud](https://packagecloud.io/tyk/tyk-sync).
### Docker
To install Tyk Sync using Docker, follow these steps:
#### Pull the Docker image from the Tyk repository
Make sure to specify the version tag you need. For example, to pull version v1.5.0, use the following command:
```bash
SYNC_VERSION=v1.5.0
docker pull tykio/tyk-sync:$SYNC_VERSION
DASHBOARD_URL is the fully qualified dashboard target URL (e.g. http://localhost:3000) and SECRET refers to the API access key use to access your Dashboard API. For dashboard users, you can get it from the “Users” page under “Tyk Dashboard API Access Credentials”.
If you prefer not to provide the secret via the command line, you can set the environment variable TYKGIT_DB_SECRET instead. This method keeps your secret secure and avoids exposure in command history.
GATEWAY_URL is the fully qualified gateway target URL (e.g. http://localhost:8080) and SECRET refers to the API secret (secret parameter in your tyk.conf file) used to access your Gateway API.
If you prefer not to provide the secret via the command line, you can set the environment variable TYKGIT_GW_SECRET instead. This method keeps your secret secure and avoids exposure in command history.
This command imports the configurations from the dev-backup directory to your staging Tyk Dashboard.
Specify Source API Configurations
For the sync, update, and publish commands, you need to specify where Tyk Sync can get the source API configurations to update the target Tyk installation. You can store the source files either in a Git repository or the local file system.
Working with Git
For any Tyk Sync command that requires Git repository access, specify the Git repository as the first argument after the command. By default, Tyk Sync reads from the master branch. To specify a different branch, use the --branch or -b flag. If the Git repository requires connection using Secure Shell Protocol (SSH), you can specify SSH keys with --key or -k flag.
A .tyk.json index file is required at the root of the source Git repository or the specified path. This .tyk.json file lists all the files that should be processed by Tyk Sync.
Automate API Configuration Management with Tyk Sync
By integrating GitHub Actions, teams can schedule backups to cloud storage, sync configurations from a Git repository, and update local API definitions directly to the Tyk Dashboard. These workflows ensure configurations are securely maintained, aligned across environments, and easily managed within the API lifecycle.
Backup API Configurations with Github Actions
API platform teams can automate configuration backups using GitHub Actions. By setting up a scheduled GitHub Action, API configurations can be periodically exported and stored in cloud storage, like AWS S3. This approach ensures backups remain up-to-date, offering a reliable way to safeguard data and simplify restoration if needed.
Create a GitHub Action workflow
In your repository, create a new file .github/workflows/tyk-backup.yml.
Add the following content to the tyk-backup.yml file:
Navigate to Settings > Secrets and variables > Actions.
Add the following variable:
TYK_SYNC_VERSION: The version of Tyk Sync you want to use.
Add the following secrets:
TYK_DASHBOARD_URL: The URL of your Tyk Dashboard.
TYK_DASHBOARD_SECRET: The secret key for your Tyk Dashboard.
AWS_S3_BUCKET: The name of your AWS S3 bucket.
AWS_ACCESS_KEY_ID: Your AWS access key ID.
AWS_SECRET_ACCESS_KEY: Your AWS secret access key.
Commit and push changes
Commit the tyk-backup.yml file and push it to the main branch of your repository.
Verify backups
The GitHub Action will run every day at midnight, dumping API configurations into a backup directory and uploading them to your specified S3 bucket.
Synchronize API configurations with GitHub Actions
API platform teams can use GitHub Actions to sync API configurations, policies, and templates from a Git repository to Tyk. Triggered by repository changes, the action generates a .tyk.json file and applies updates with the sync command, keeping the Tyk setup aligned with the repository.
Setup GitHub repository
Organize your repository with the following structure:
/apis/ for API definition files.
/policies/ for security policy files.
/assets/ for API template files.
Create a GitHub Action workflow
In your repository, create a new file .github/workflows/tyk-sync.yml.
Add the following content to the tyk-sync.yml file:
Navigate to Settings > Secrets and variables > Actions.
Add the following variable:
TYK_SYNC_VERSION: The version of Tyk Sync you want to use (e.g., v2.0.0).
Add the following secrets:
TYK_DASHBOARD_URL: The URL of your Tyk Dashboard.
TYK_DASHBOARD_SECRET: The secret key for your Tyk Dashboard.
Commit and push changes
Commit the tyk-sync.yml file and push it to the main branch of your repository.
Verify synchronisation
Each time there is a change in the repository, the GitHub Action will be triggered. It will create the .tyk.json file including all JSON files in the repository and use the sync command to update the Tyk installation.
Update API Definitions locally
For API developers managing definitions locally, Tyk Sync's publish or update commands can upload local API definitions directly to the Tyk Dashboard, streamlining updates and keeping definitions in sync during development. Follow these steps to update your API definitions locally.
Prepare your API Definition
Create your API definition file and save it locally. For example, save it as api1.json in a directory structure of your choice.
Create a .tyk.json index file
In the root directory of your API definitions, create a .tyk.json file to list all API definition files that Tyk Sync should process.
-d, --dashboard DASHBOARD_URL: Tyk Dashboard URL (required) -h, --help: Help for the dump command -t, --target PATH: Target directory for output files (optional) -s, --secret SECRET: API secret for Dashboard access (optional) --apis IDS: Specific API IDs to dump --oas-apis IDS: Specific OAS API IDs to dump --policies IDS: Specific policy IDs to dump --templates IDS: Specific template IDs to dump
publish: Publish a specific example show: Show details of a specific example
Flags
-h, --help: Help for examples command
Example
tyk-sync examples
Examples Show Command
Aspect
Details
Command
tyk-sync examples show
Usage
tyk-sync examples show [flags]
Flags
-h, --help: Help for show command -l, --location string: Location of the example
Example
tyk-sync examples show --location="udg/vat-checker"
Examples Publish Command
Aspect
Details
Command
tyk-sync examples publish
Usage
tyk-sync examples publish [flags]
Flags
-b, --branch string: Branch to use (default "refs/heads/main") -d, --dashboard string: Dashboard target URL -g, --gateway string: Gateway target URL -h, --help: Help for publish command -k, --key string: Key file location for auth -l, --location string: Location of the example -s, --secret string: API secret --test: Use test publisher, output to stdio
-b, --branch BRANCH: Git branch (default "refs/heads/master") -d, --dashboard DASHBOARD_URL: Dashboard URL -g, --gateway GATEWAY_URL: Gateway URL -h, --help: Help for publish command -k, --key SSHKEY: SSH key file location -p, --path PATH: Source file directory -s, --secret SECRET: API secret --test: Use test publisher --apis IDS: Specific API IDs to publish --oas-apis IDS: Specific OAS API IDs to publish --policies IDS: Specific policy IDs to publish --templates IDS: Specific template IDs to publish
-b, --branch BRANCH: Git branch (default "refs/heads/master") -d, --dashboard DASHBOARD_URL: Dashboard URL -g, --gateway GATEWAY_URL: Gateway URL -h, --help: Help for update command -k, --key SSHKEY: SSH key file location -p, --path PATH: Source file directory -s, --secret SECRET: API secret --test: Use test publisher --apis IDS: Specific API IDs to update --oas-apis IDS: Specific OAS API IDs to update --policies IDS: Specific policy IDs to update --templates IDS: Specific template IDs to update
Tyk Sync allows you to dump configurations to a local directory, which can then be committed to a Git repository. This enables version control and easy synchronization across environments.
Can I sync multiple APIs to a single Git repository?
Yes, you can store multiple API definitions, policies, and other Tyk resources in a single Git repository. Tyk Sync and Tyk Operator can work with multiple resources in the same directory.
It's a good practice to maintain separate branches or tags for different environments to make rollbacks easier.
</details>
<details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/5921/files#diff-a6789c66bfa0660f7fdbe4796002ab4777677bae59a0276689c840100ff0b0b2R154-R170'><strong>Menu Structure Consistency</strong></a>
Verify that the new menu structure for "Automations Tools" and its subcategories is consistent with the rest of the menu and correctly links to the intended pages.</summary>
```yaml
- title: "Automations Tools"
category: Directory
show: True
menu:
- title: "Overview"
path: /api-management/automations
category: Page
show: True
- title: "API Management in Kubernetes"
path: /api-management/automations/operator
category: Page
show: True
- title: "Synchronizing Tyk Configuraiton"
path: /api-management/automations/sync
category: Page
show: True
- title: "API Versioning"
Correct the spelling of "Configuraiton" in the title "Synchronizing Tyk Configuraiton" to "Configuration" to ensure proper readability and professionalism.
Why: Correcting the spelling of "Configuraiton" to "Configuration" improves the professionalism and readability of the documentation. This is a clear and necessary fix.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
For internal users - Please add a Jira DX PR ticket to the subject!
Preview Link
https://deploy-preview-5921--tyk-docs.netlify.app/docs/nightly/api-management/automations/
Description
Screenshots (if appropriate)
Checklist
master.PR Type
Documentation, Enhancement
Description
Added a comprehensive guide for Tyk Sync, detailing its features, setup, and usage.
Restructured the Automations section in the documentation with new subcategories.
Introduced a new page for synchronizing Tyk configurations using Tyk Sync.
Updated the menu structure to reflect the new Automations Tools hierarchy.
Changes walkthrough 📝
sync.md
Added comprehensive Tyk Sync documentation.tyk-docs/content/api-management/automations/sync.md
menu.yaml
Updated menu structure for Automations Tools.tyk-docs/data/menu.yaml