Github Support#

Overview#

cookietemple uses GitPython and PyGithub to automatically create a repository, add, commit and push all files. Moreover, issue labels, a development and a TEMPLATE branch are created. The TEMPLATE branch is required for Syncing your project to work and should not be touched manually.

Branches#

Overview#

git branches can be understood as diverging copies of the main line of development and facilitate parallel development. To learn more about branches read Branches in a Nutshell of the Pro Git Book. A simple best practice development workflow follows the pattern that the master/main branch always contains the latest released code. It should only be touched for new releases. Code on the master/main branch must compile and be as bug free as possible. Development takes place on the development branch. All in parallel developed features eventually make it into this branch. The development branch should always compile, but it may contain incomplete features or known bugs. cookietemple creates a TEMPLATE branch, which is required for Syncing your project to work and should not be touched manually.

Branch protection rules#

cookietemple sets several branch protection rules, which enforce a minimum standard of best branch practices. For more information please read about protected branches. The following branch protection rules only apply to the master/main branch:

  1. Required review for pull requests: A pull request to master/main can only be merged if the code was at least reviewed by one person. If you are developing alone you can merge with your administrator powers.

  2. Dismiss stale pull request approvals when new commits are pushed.

Github Actions#

Overview#

Modern development tries to merge new features and bug fixes as soon as possible into the development branch, since big, diverging branches are more likely to lead to merge conflicts. This practice is known as continuous integration (CI). Continuous integration is usually complemented with automated tests and continuous delivery (CD). All of cookietemple’s templates feature Github Actions as main CI/CD service. Please read the Github Actions Overview for more information. On specific conditions (usually push events), the Github Actions workflows are triggered and executed. The developers should ensure that all workflows always pass before merging, since they ensure that the package still builds and all tests are executed successfully.

main_master_branch_protection workflow#

All templates feature main_master_branch_protection workflow. This workflow runs every time a PR to your projects master or main branch is created. It fails, if the PR to the master/main branch origins from a branch that does not contain patch or release in its branch name. If development code is written on a branch called development``and a new release of the project is to be made, one should create a ``release branch only for this purpose and then merge it into master/main branch. This ensures that new developments can already be merged into development, while the release is finally prepared. The patch branch should be used for required hotfixes (checked out directly from master/main branch) because, in the meantime, there might multiple developments going on at development branch and you dont want to interfere with them. Pull requests against the master or main branch should not contain any SNAPSHOT versions, since they are only used for development versions.

release drafter workflow#

All templates feature release-drafter workflow. This workflow consists of two parts: Every time a new PR is made, the workflow runs and tries autolabeling the PR either as feature or bug. Feature PRs introduce new features if the branch name contains “feature”. Bug PRs are PRs that either have a title containing “fix” or the branch name contains “fix”. This Action then drafts a new release grouped by the different PR categories and include references and titles to all PRs inclduded in the new release. One can read more about this at the Release drafter GitHub repo.

sync_project.yml#

All templates also feature this workflow. This workflow is used for automatic syncing (if enabled) your project with the latest cookietemple template version. The workflow is run every night, although this behavior can be customized if desired. The workflow calls cookietemple sync, which first checks whether a new template version is available and if so it submits a pull request. For more details please visit Syncing your project.

Secrets#

Github secrets are what their name suggests: Encrypted secret values in a repository or an organisation; once they are set their value can be used for sensible data in a project or an organisation but their raw value can never be seen again even by an administrator (but it can be updated).

Cookietemple uses a secret called CT_SYNC_TOKEN for its syncing feature. This secret is automatically created during the repo creation process, if you choose to create a GitHub repo. The secret contains your encrypted personal access token as its value. Note that this will have no effect on how to login or any other activity in your project. If you remove the secret or change its value (even with another personal access token of you) the syncing feature will no longer work. In case you are creating an organisation repository, the secret will also be stored as a repository secret, only usable for your specific project.

See section below in case your Github repo creation failed during the create process.

Error Handling due to failed Github repository creation#

Errors during the create process due to a failed Github repo creation may occur due to a vast amount of reasons: Some common error sources are:

  1. You have no active internet connection or your firewall protects you against making calls to external APIs.

2. The Github API service or Github itself is unreachable at the moment, which can happen from time to time. In doubt, make sure to check the Github status page.

  1. A repo with the same name already exists in your account/your organisation.

  2. Your Github Token/Secret does not have all required permissions (all repository and workflow permissions).

Creation fails, ok: But how can I then access the full features of cookietemple? You can try to fix the issue (or wait some time on case, for example, when Github is down) and then process to create a Github repository manually. After this, make sure to create a secret named CT_SYNC_TOKEN with the value of your PAT for your repository. See the Github docs for more information on how to create a secret.

We’re planning to provide a command like cookietemple config fix-github that tries to create a Github repo, set the secret and all other stuff that is going on during the Github repository creation in the create process in a later version.

Issue labels#

cookietemple’s Github support automatically creates issue labels. Currently the following labels are automatically created: 1. dependabot: All templates, which include Dependabot support label all Dependabot pull requests with this label.