Octopus.Migrator shoud not use meaningless "IDs"
Since the content type and name is obviously a unique key (particularly when exporting to files), Migrator should use the name (prefixed by the type name) as the key when linking from other resources, rather than a phony ID that changes when you import.
That is, rather than a Team having MemberUserIds = [ "Users-1" ] it should have MemberUsers = [ "Users-BobCratchet" ] which is both more comprehensible, and unlikely to change in a simple import and re-export.
We do modifications to our Octopus by exporting from production, importing on a dev system, altering, and re-exporting. However, the IDs always change in this process, leading to unnecessarily long and pointless code-reviews of changes.
For instance: Currently, if we create UserRoles with the name "Coordinator" and then "Broadcaster" and then "Alpha Tester" -- and then export, we see that they get IDs like "userroles-1" and "userroles-2" ... in order of creation. If the change is to add a new role like "Beta Tester" ... then even that new export won't be in alphabetical order, and the next import/export to a clean system will change the IDs again.
Dan Ward commented
You might want to check out a project I just released; by itself it might not do everything you want but will get you a long way there:
Octopus Deploy Utilities allows you to export your Octo configuration using the REST API but also post-processes your data, doing the ID -> name lookups you are looking for. It does this by adding new properties to the JSON: for any *Id property it add a *Name. So for a Teams MemberUserIds it adds MemberUserNames with the user names. For projects it'll add ProjectGroupName, LifecycleName, IncludedLibraryVariableSetNames, ClonedFromProjectName. For variables it does that for the Scope Environment, etc. fields but also goes an extra step adding a Scope.Breadth property which aggregates all the individual Scope values, simplifying programmatic usage.
It does more than ID -> name lookups, though; for a project it'll add the actual deploy process configuration and project variable variable set along with the any included library variable sets. More notes about the post-processing are here:
That said, this project is only for exporting the data, not pushing it back up. But you can easily use this with your scripts: the oduobject alias pulls in all the data from an export into a single PowerShell object. You could then very easily parse through the config, filtering for the object you are looking for by name, then grab it's Id. This returns the Id of the UserRole named 'TestRole':
((oduobject).UserRoles | ? Name -eq 'TestRole').Id
Hope this helps!