[NEW FEATURE] Allow forking other github repositories to init new repositories.

[onnimonni]

It is really typical for companies to use git repositories as project templates which are then forked into client projects. It would be very cool if terraform could initiate a fork from selected github repository.

Terraform Version

Terraform v0.9.11

Affected Resource(s)

• github_repository

Terraform Configuration Files

This is just an example that I would want to see:

resource "github_repository" "client-project" {
  name        = "client-project"
  description = "My client project from template"
  
  # The fork directive could look something like this:
  fork_from_repository = "onnimonni/project-template"
}

References

This has some similarities from #7 but just initiating a new repo by forking it from another repo would be enough for me.

• https://github.com/terraform-providers/terraform-provider-github/issues/7

[grubernaut]

API Reference: https://developer.github.com/v3/repos/forks/

[onnimonni]

Hard thing here is that the api https://developer.github.com/v3/repos/forks/#create-a-fork doesn't allow changing the name of the fork immediately.

So this would only work if the user doesn't already have the same named repository.

Edit: And it doesn't allow multiple forks for one organisation. I contacted support@github.com about these restrictions but until those are easier I think we shouldn't do this.

[onnimonni]

So actually the import api looks better suited for this: https://developer.github.com/v3/migration/source_imports/

It's just much more slower than forking.

But on the brightside then we could support importing from multiple version systems. (currently: GIT, SVN, Hg and TFS)

[majormoses]

It is supported in the upstream golang library: https://github.com/google/go-github/blob/v15.0.0/github/repos_forks.go#L57-L85 and https://github.com/google/go-github/blob/v15.0.0/github/migrations_source_import.go I think both use cases make sense. One thing to note about if you are looking to take a client project I think import is more appropriate because it can be made private. With a fork in order to break the fork and make it private I believe you have to engage github support from what I recall. This could have been changed so take it with a grain of salt.

[jcudit]

👋 @onnimonni - does support for Template Repositoiesy help to solve your use case? Or is forking of other repositories still a need?

[majormoses]

@onnimonni - does support for Template Repositoiesy help to solve your use case? Or is forking of other repositories still a need?

I think they are different use cases, its fairly common to need to be able to fork an upstream open source project and start consuming it until your changes have been accepted upstream.

[kpfleming]

Agreed we do this too, and for now I perform the forking operation outside of Terraform (and make some content changes to the new repository), then add it to Terraform for management from that point forward.

[majormoses]

I think given that you can't have multiple forks of the same upstream repository in an org and I am not sure the majority of use cases would need requiring renaming and such. Maybe we should not specify a name in a fork resource keeping that matching the api calls. It could assign the name based on the source of the fork. The org you fork into would be implied from the github provider definition. I think the resource would look something like:

resource "github_fork" "upstream-project" {
  name        = "org/repository" // this is remote target
}

This would represent only the fork itself, you could then create a repository definition to change further properties though it would require an import but it could look something like this

resource "github_repository" "forked-project" {
  name = github_fork.upstream-project.repository_name
  ...
}

Not sure I have thought it through all the way but I think this could make sense.

[kpfleming]

That sounds too complicated to me :-)
I'd rather create a github_repository resource to represent the repository after the fork, and then create some sort of syntax for terraform import to have the fork created during import.

[mbrowne]

@kpfleming One of the things we like about Terraform at my company is that it enables all developers to submit pull requests to create new repos or do anything else we're managing with Terraform. And the permission to create repos directly in GitHub is restricted to one or two admins, because we want to ensure that everyone is using Terraform for this (in fact we have a script that runs nightly and overwrites any manually changed settings with what's in Terraform). So for us it wouldn't be ideal to require a developer to request an admin to fork a repo for them before they could create it - we would much rather provide a way for developers to do that themselves via TF.

[majormoses]

That sounds too complicated to me :-)
I'd rather create a github_repository resource to represent the repository after the fork, and then create some sort of syntax for terraform import to have the fork created during import.

If you manually fork, import, and use the existing github_repository isn't that basically the same thing minus the automagic create on import? I don't think import should ever create resources. This actually seems more complicated to me than to have a resource that represents the fork and allow this to be stitched together with existing resources. If you find it too complicated I think that such stitching logic could easily be implemented in your own orgs module. I think we should consider that not everyone will have need to tweak it, thus forcing a whole resource definition for it and making people grab the list of tags and such seems like its more complicated for those use cases. Fork is its own API and for these reasons I think the resources (fork vs repository) should be separate.

Echoing the same as above, we try to limit the number of admins and restrict forking to admins only. This allows anyone to submit a request for a fork and if its reasonable lots of people can approve it since the token and user that terraform is being run with has the permissions required.

[kpfleming]

We're in almost exactly the same situation (limited number of admins, forks have to be requested), but we also make quite a few content changes to repositories that we fork so the actual fork operation is done by a script outside of Terraform, and then the repository is imported into Terraform for further management.

Now that I think about it, the 'fork' operation as a Terraform activity might work quite well, as I could use a local-exec provisioner to execute the script to modify the repository contents after the fork has been created.

I think I'd be OK with the original proposal in this issue, just adding a suitable argument to the github_repository resource to tell it that it should create the repository by forking. If the user has also provided a name for the fork, then that can be applied in a second API call after the fork is done.

[fgreinacher]

@jcudit I just noticed you removed this from the v4.19.0 milestone. I'd be willing to support getting this in! Does it make sense to look at the linked draft MRs or do you want to go in a different direction?

[jcudit]

@fgreinacher would ❤️ a contribution here. Reviving the linked PR sounds like the right path.

[ryan-lane]

I'd really love to have this feature, as it means I can't fully manage an organization without it, and that means public forks have to be handled differently than public repos, which isn't great for security (for us and for anyone else that may depend on a fork).

[fgreinacher]

@fgreinacher would ❤️ a contribution here. Reviving the linked PR sounds like the right path.

Sorry, we went for another approach to solve our use-case. I therefore won't be able to contribute this 😬

[github-actions]

👋 Hey Friends, this issue has been automatically marked as stale because it has no recent activity. It will be closed if no further activity occurs. Please add the Status: Pinned label if you feel that this issue needs to remain open/active. Thank you for your contributions and help in keeping things tidy!

[milldr]

bump. 👍 for this feature

[philippeboyd]

Almost 6 years later... Would also like this feature!

@fgreinacher I'm curious on what was your workaround for this? Manually creating the fork and then link it to TF using the datasource repository?

[fgreinacher]

@philippeboyd We actually went for an Ansible-based solution 😅

[dpiotrowski-sstudio]

Hard thing here is that the api https://developer.github.com/v3/repos/forks/#create-a-fork doesn't allow changing the name of the fork immediately.

@onnimonni I don't think this is the case any more. The docs (note the apiVersion=2022-11-28 parameter in the URL) explicitly state you can provide a new name while requesting a fork:

name string
When forking from an existing repository, a new name for the fork.