Setup Deploy Keys

CircleCI Setup

A GitHub fine-grained access token is needed to give CircleCI jobs publish-changelog and tag-and-release the ability to write to the repo for the follow features:

Push change for the CHANGELOG.md to the repo, make and merge pull request.
Publish a release tag.

Setup A GitHub Personal Access Token

This is used to push branches, for updating the CHANGELOG, and then merging it to your main branch by making a pull request. It is also used to publish a release.

Login into GitHub
Go to your profile settings
click "Developer Settings" > "Personal access tokens" > "Fine-grained tokens"
click the "Generate new token"
Set the "Resource owner" to the organization of the repositories that you need write access to.
Set "Expiration" from 7 days to "No expiration" (that is the longest you can set it at this time of writing).
Set "Repository access" to the option that contains the repos you need write access to.

Select the following "Permissions" options:

Permissions
  Commit statuses Access: Read-only
  Contents Access: Read and Write (needed to push files, make commits)
  Metadata Access: Read-only (You cannot turn this off)
  Pull requests Access: Read and Write (needed to open pull-request)

Go to CircleCI App, then select your organization.
Select "Organization Settings" > "Context".
Select the appropriate context (it should be one that the repos has access to).
Click the "Add Environment variable" button and paste the fine-grained token as the variable GH_WRITE_TOKEN.

That finises up this section.

NOTE: Without this setup the jobs will fail in CircleCI.

Setup A CircleCI API Token

You will also need a CircleCI Token for accessing the API to trigger workflows.

Go to your "User Settings" and then select "Personal API Tokens".
Click the "Create New Token" button and save it as "CircleCI Automated Releases" (or give it any name you like).
Save the token as CIRCLE_TOKEN in the same context as the GH_WRITE_TOKEN.

NOTE: GH_WRITE_TOKEN and CIRCLE_TOKEN variable names cannot be changed as they are hardcoded into the AVR application.

GitHub Actions

Fined-Grained Access Token

WARNING: If you make a new repository after creating a fine-grained token, you may get 404 when making API requesting such as repos/{owner}/{repo}/pulls. The fix was generating a new token in my case.

Go to your settings page and Developer settings > Personal Access Tokens:
Make a fine-grained personal access token with the following permissions:

NOTE: Be sure to select which organization you want to use the token with:
If this is for an organization you'll need to have it approved before it can access any of those repositories. For details see Setting a personal access token policy for your organization Also, you can test the token with curl:
```
curl -i -H "Authorization: Bearer ${GH_WRITE_TOKEN}" https://api.github.com/repos/<your-repos>/pulls
```
Add the token as the GH_WRITE_TOKEN secret, either in the repository settings or the organization settings.

NOTE: You need to have a paid plan to use organization secrets in private repositories.

Make the directories and file .github/workflows/auto-version-release.yml in your repository with the contents:

 name: auto-version-release
 on:
   pull_request:
     branches: [main] # pull request that target these branches.
     types: [closed]

 concurrency:
   group: release-group
   cancel-in-progress: true

 run-name: ${{ github.actor }} run avr workflow-selector

 jobs:
   selector: # trigger this on push to main and only when a PR merge.
     uses: kohirens/version-release/.github/workflows/selector.yml@5.0.4
     name: workflow-selector
     secrets:
       github_write_token: ${{ secrets.GH_WRITE_TOKEN }}
     with:
       committer_email: <email-of-your-choice>
       committer_name: <name-of-your-choice>

Pass the secret to the selector job in your workflow.

jobs:
  selector: # trigger this on push to main and only when a PR merge.
    uses: kohirens/version-release/.github/workflows/selector.yml
    name: workflow-selector
    secrets:
      github_write_token: ${{ secrets.GH_WRITE_TOKEN }}

NOTE: Even though were running GitHub Actions which will automatically generate a temporary GITHUB_TOKEN for use in steps; it is prevented from triggering any additional actions/workflows we may want to run. Assume this is a security measure and hand-holding for those new to GitHub Actions. However, when we publish the change log then merge it in, we'll need the workflow-selector to run once more, automatically, to decided if a release should be published.

GitHub App Auto-Version-Release

You can grant this application access using the GitHub App.

In the upper-right corner of any page on GitHub, click your profile photo.
For a personal account, navigate to your account settings or for an organization, Click Your organizations and navigate to the organization Settings.
In the left sidebar, click Developer settings.
In the left sidebar, click GitHub Apps.
Next to the GitHub App that you want to install, click Edit.
Click Install App.
Click Install next to the location where you want to install the GitHub App.
If the app requires repository permissions, select All repositories or Only select repositories. The app will always have at least read-only access to all public repositories on GitHub.
If the app does not require repository permissions, these options will be omitted.
If you selected Only select repositories in the previous step, under the Select repositories dropdown, select the repositories that you want the app to access.
If the app creates any repositories, the app will automatically be granted access to those repositories as well.
Click Install.

FilesExpand file tree

setup-keys.md

Latest commit

History