A new project can look ready while its first contributor is still stuck. The repository has a pipeline file, but no runner can pick up the job. The tests pass, but nobody knows who should review the change. A teammate eventually explains the missing setup in chat, and the next team has to ask the same questions.
A supported starting point should help a team get through its first contribution and understand how to keep the project running afterward. The files matter, but so do access, dependencies, and a clear place to ask for help.
Start with a familiar kind of project
One common workload is enough to begin with. A service your organization builds regularly gives you existing projects and people to learn from. Looking at how a recent team got started will show which parts were routine and which depended on someone knowing an undocumented setting.
The first version should cover those recurring needs. For a service, that might mean a small application, a test command, a pipeline using the supported build approach, and instructions for requesting the access it needs. Credentials should come from an approved credential store or appropriately restricted CI/CD configuration, never from files copied into the repository.
A documentation site is unlikely to need the same deployment permissions or checks as that service. Separate starting points are easier to understand when the differences reflect how projects are built and operated. If teams routinely delete half a template before using it, that's a reason to reconsider what belongs in it.
Choose what gets copied and what stays maintained elsewhere
Project templates give a new repository an initial set of files. Custom group templates make those choices available during project creation.1 A team can then adapt its application code and project-specific instructions. Later edits to the template don't automatically update those copies, so each template needs a plan for changes that existing projects should receive.
Frequently reused build logic is often better maintained as a versioned CI/CD component. Consumers choose a release or commit SHA, supply documented inputs, and review upgrades. That gives the component's maintainers a place to fix common problems without turning every consuming project's pipeline into a separate implementation. Reusable pipelines that teams can adopt and maintain explains how to introduce that approach and support its consumers.
Group defaults and security policies have different jobs again. A default provides an initial choice; it isn't necessarily a restriction on what a project maintainer can change. Where a control must apply consistently, the team responsible for it should choose and manage an enforcement mechanism, such as a pipeline execution policy where available.2 A template file alone doesn't enforce a rule.
Try the setup with the access contributors will have
The people maintaining the starting point usually know the surrounding platform well and may have broader permissions. A colleague who hasn't used it before can reveal gaps that are easy for them to miss. Give that colleague the normal project-creation and contribution access, then ask them to make a small change through the documented process.
Their first pipeline should have the runner, inputs, and package access it needs. If a permission request is intentional, the instructions should explain who handles it and what the contributor can do while waiting. If a job fails because setup is incomplete, its output should help them distinguish that from a problem in their code.
Review deserves the same attention. The new project needs someone who can accept a change and answer questions. Copied reviewer names or a CODEOWNERS file can become stale or refer to people who aren't eligible in the new project. When Code Owner approval is part of the setup, check it in the created project with the intended reviewers.3 Protected changes with independent review covers the review choices behind those settings.
Give existing projects a way to keep up
An update to the starting point should explain what existing teams need to do, if anything. A spelling correction in a sample README is different from a fix to a build configuration or a change in a supported runtime. Teams need that distinction to decide when to act.
For copied files, maintainers can describe the change and offer a focused merge request or migration instructions. For components, a versioned release lets consumers try the update and retain their current version if they encounter a problem. Trying the change in representative consuming projects first makes those instructions more reliable.
Retiring a starting point also takes preparation. Its page should direct new teams to the replacement, while existing users have a named support contact and enough notice to move. A project that still depends on an older version shouldn't lose its only instructions just because a new template is available.
Learn from the adaptations teams make
Teams will encounter requirements that the starting point doesn't cover. A documented way to propose an improvement or request an exception lets maintainers understand those needs. The discussion should explain what the team is trying to accomplish and which shared controls still apply. Platform rules teams can maintain describes how to handle those decisions without relying on informal permissions.
Repeated adaptations are worth investigating together. Several teams replacing the same deployment job may indicate a missing supported option. One unusual integration may be better kept in its own project. The aim is to reduce repeated setup work while leaving teams room to own their applications.
Following a new team's first change, and an existing team's first upgrade, gives you a practical review of the starting point. Both should be understandable without its original author being present.
Further Reading
Notes
-
Custom group project templates are available in Premium and Ultimate. On Free, you can provide a documented starter repository for teams to copy and configure; it isn't the same integrated project-creation experience. ↩
-
Pipeline execution policies are available in Ultimate. They can require centrally managed pipeline configuration; a copied template or an optional component doesn't provide equivalent enforcement. ↩
-
Code Owners is available in Premium and Ultimate. Required Code Owner approval also depends on the protected branch configuration. Teams on Free can document maintainers and review expectations without that enforced ownership rule. ↩
- Custom project templates for groups explains how to offer maintained starting projects during project creation.
- CI/CD components covers reusable configuration, inputs, versions, and publishing.
- Protection rules and permissions explains how overlapping group and project rules affect a newly created project.