Creating a new app repository

These instructions will help you create a new app repository based on our repository template.

Prerequisites

• the git CLI
• the GitHub CLI gh
• devctl version 6.12.0 or newer

Step 1 - Preparation

Since you will need the app and repository name several times on the command line, we first create an environment variable APP_NAME with the new repository name as the value.

Example:

export APP_NAME=something-awesome

Here we assume you want to create the new app and repository named something-awesome.

Note regarding naming: Please don’t let your repository name end with -app. And make sure that the repository and the chart can be named identically. This will help us in day-to-day life.

Step 2 - Repo creation

In your current command line / shell session, navigate to the directory where you keep git clones.

Note: No need to create an empty sub folder just for the new repo, as this will happen automatically in the next step.

Now create the repository, using our repository template to pre-fill its content. Execute this command to create the new public repository:

gh repo create \
  --clone \
  --public \
  --template=giantswarm/template-app \
  giantswarm/${APP_NAME}

Note: The above command will create a public repository and the repo will include the Apache 2.0 license. You can replace the flag --public with --private to create a private repository instead.

Step 3 - Name replacement

Let’s fill in the actual app name in a bunch of places in the new repo’s content, as otherwise we would have just the placeholder {APP-NAME} in there.

Make sure to navigate into your local clone of the repository:

cd ${APP_NAME}

Here are your commands to run:

mv helm/APP-NAME helm/${APP_NAME}

devctl replace \
  -i '{APP-NAME}' ${APP_NAME} \
  --ignore '.git/**' '**'

Commit and push these replacements:

git commit -a -m "Replace placeholder by ${APP_NAME}"
git push origin $(git rev-parse --abbrev-ref HEAD)

Step 4 - Configure settings

Now configure the GitHub repository settings (permission, branch protection, Renovate access, etc.) with one simple command:

devctl repo setup giantswarm/${APP_NAME}

Step 5 - Set up repository automation

To maintain team ownership and keep the repository up-to-date with our standards, you should add the new repository to your team’s list in giantswarm/github. See the README for more details.

Step 6 - Final touches

• On the repository home page near About, click the cog icon to adjust the repository description and tags. Under “Include in the home page” de-select the Packages and Environments options.
• Add documentation to the docs/ folder.
• Replace the README.md of your new repository with meaningful info about the software you’re offering there.
• Learn how to publish the app in a catalog