Import from GitHub
If the GitHub project contains references to entities that do not already exist in YouTrack, they are created. The user account that you use to run the import should have permission to create projects, issues, users, and possibly more. We recommend that you use an account with a System Admin role to execute the import script.
New entities are created as follows:
|Projects||If the project that is referenced in the import source does not already exist, a new project is created. |
If your GitHub project contains the special characters
|Users||Several issue attributes like |
References to users in the imported data are mapped to existing accounts in YouTrack. If a match is not found, a new user account is created.
Imported users are allocated a license according to your subscription plan. For users that exceed your per-user license limit, the imported users are flagged as banned.
For more information, see Ban User Accounts.
|Custom Fields||If the import data contains a field that does not exist in YouTrack, the custom field is created and added to the target project. |
|Field Values||If the source file contains new values for an existing field, they are added to the current set of values.|
Set Up Your Environment
Import to YouTrack is supported by Python import scripts. These scripts are built on top of the YouTrack REST API. You won't actually need to do any programming in Python, but you do need to install Python and the package that contains the import scripts.
To set up your environment:
- Download and install Python. The import scripts are compatible with Python 2.7+. Python 3 releases are not supported. You can choose whichever installation directory you prefer.
The latest versions of macOS, CentOS, Red Hat Enterprise Linux (RHEL), and Ubuntu come with Python 2.7 out of the box. If you're working with any of these operating systems, continue with the next step.
- Install the package that contains the import scripts. Open the command-line interface that is supported by your operating system and enter the following command:
pip install youtrack-scripts
- The import scripts are installed in your local environment.
youtrackpackage that contains the Python client library for the YouTrack REST API is installed automatically as a dependency.
pip install --user youtrack-scripts
Import Your Data
The last step is to run the command that imports your data from GitHub.
To import your data:
- Open the command-line interface that is supported by your operating system.
- If necessary, change the current directory to the installation directory for Python. For example (Windows):
- Enter the following command: Replace the command-line parameters with values as described here:
github2youtrack -t token -u login -p password target_url github_user github_password github_repo
When used with the
-toption, a permanent token that is used to authenticate your administrator account in YouTrack. This is the preferred method of authentication. If you use this option, skip the
-poptions. To learn how to generate a permanent token, see Manage Permanent Tokens.
Alternatively, you can use the
-Toption and specify the full path and filename for a file that contains a permanent token.
When used with the
-uoption, the login for a YouTrack administrator account. You must also specify a value for the
When used with the
-poption, the password for the YouTrack administrator account.
The base URL of the target YouTrack server. For YouTrack InCloud instances, your base URL includes the trailing
/youtrack. For example:
The username of the account that you use to log in to GitHub.
The password for the account that you use to log in to GitHub.
The name of the GitHub repository that you want to import issues from. If the owner of the repository is not the same user that is specified for the
github_userparameter, reference the repository with the format
- The command executes the Python import script.
- If successful, the following line is printed in the command-line interface for each issue:
Issue [ <issue ID> ] imported successfully
- Check the project or projects that you imported issues into and verify that the data is presented properly. If you are not satisfied with the results and want to re-import the data:
- Delete all of the issues that were created during import. If you imported issues into a new project, simply delete the project.
- Run the import script again.
The import script maps data from issues in GitHub to issue attributes in YouTrack. For custom fields, the following mapping is applied:
If you encounter any errors when you run the import script, see if any of the following conditions apply.
|Cause||The value that you used for the |
|Solution||Change the value of the |
|Cause||The user account that you used to run the import script does not have permission to read or update the target resource. The resource URL indicates which entity is not accessible to the user.|
|Solution||Run the import script with a user account that has sufficient permissions to update the target resource.|