GitHub Api Workflows

Deprecation Notice

27 March 2023 Replacement: https://github.com/jpshrader/github-workflows

Setup

This project utilises Visual Studio Dev Containers to manage dependencies. For more information on VS Code Development Containers, see the following:

1. https://code.visualstudio.com/download
2. https://code.visualstudio.com/docs/remote/containers
3. https://code.visualstudio.com/learn/develop-cloud/containers

References:

1. PyGitHub API Reference
2. PyGitHub API Object Reference
3. Python Requirements file

Community Resources

• Contributing Guide
• Code of Conduct
• License
• Security Policy

Development

Linting

To perform linting, run the following command in the root of the project. Linting rules are managed in the .pylintrc file.

pylint $(git ls-files '*.py')

Testing

To run tests, execute the following command in the root of the project.

pytest

Usage

Working examples: https://github.com/jpshrader/github-api-workflow-examples

name: 'Run GitHub Utility'

on:
  workflow_dispatch:
    inputs:
      instructions:
        description: 'GitHub Utility instruction set to use'
        type: choice
        options:
          - './list-empty-branches.yml'
          - './list-unprotected-branches.yml'
          - './merge-branch.yml'
        required: true
      access_token:
        description: 'GitHub Api Access Token'
        type: string
        required: true

jobs:
  execute:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: jpshrader/github-api-workflows@main
        with:
          file_type: yaml
          access_token: ${{ github.event.inputs.access_token }}
          instructions: ${{ github.event.inputs.instructions }}

Argument	Description	Example Value	Required	Supported Value(s)
access_token	GitHub personal access token for user	N/A	true	N/A
instructions	path to instructions file	./list-empty-branches.yml	true	N/A
file_type	file format for instructions	yaml	true	yaml

Authentication

This utility uses GitHub Personal Access Tokens to authenticate with the api. As a consequence, all actions performed through this utility will be 'done by' the owner of the token.

In your consuming consuming workflow, you may accept the access token as a parameter or store it as a secret.

Token permissions

This will of course vary on the types of operations you're performing, but at the least your token will probably need these permissions:

• repo
• user

Merge branches

The merge_branch instruction checks whether there are changes to merge from from_branch to to_branch. If there are, it creates a new branch (merge-{from_branch}-to-{to_branch}-{timestamp}) off of to_branch, merges from_branch into that new branch, and then opens a pull request targeting to_branch. The title, labels, and reviewers of the resulting PR can also be passed to this instruction.

Examples:

- action: merge_branch
  repo_name: jpshrader/github-api-workflows
  from_branch: main
  to_branch: test
  title: merge
  labels:
    - bug
    - documentation
  reviewers:
    - jpshrader

Argument	Description	Example Value	Required	Default Value
repo_name	the full name of a repo (ex. {owner}/{slug})	jpshrader/github-api-workflows	true	N/A
from_branch	name of the origin branch	main	true	N/A
to_branch	name of the destination branch	main	true	N/A
title	title of the resulting PR	merge branch	false	Merge {from_branch} to {to_branch}
labels	a list of label names to add to the PR	bug	false	[]
reviewers	a list of user logins to request reviews from	jpshrader	false	[]

List Empty Branches

The list_empty_branches instruction iterates over every branch in a given repo and prints a list of branches that are:

• Not protected
• Not the target_branch
• 0 commits ahead of target_branch

Examples:

- action: list_empty_branches
  repo_name: jpshrader/github-api-workflows
  target_branch: main
  include:
    - test
  exclude: 
    - jawn

Argument	Description	Example Value	Required	Default Value
repo_name	the full name of a repo (ex. {owner}/{slug})	jpshrader/github-api-workflows	true	N/A
target_branch	name of the branch to diff against	main	false	Default branch of repo
include	a list of branch names to include (uses string contains to match)	feature/	false	[]
exclude	a list of branch names to ignore (uses string contains to match)	releases/	false	[]

Delete Empty Branches

The delete_empty_branches instruction iterates over every branch in a given repo and deletes all branches that are:

• Not protected
• Not the target_branch
• 0 commits ahead of target_branch

Examples:

- action: delete_empty_branches
  repo_name: jpshrader/github-api-workflows
  target_branch: main
  include:
    - test
  exclude: 
    - jawn

Argument	Description	Example Value	Required	Default Value
repo_name	the full name of a repo (ex. {owner}/{slug})	jpshrader/github-api-workflows	true	N/A
target_branch	name of the branch to diff against	main	false	Default branch of repo
include	a list of branch names to include (uses string contains to match)	feature/	false	[]
exclude	a list of branch names to ignore (uses string contains to match)	releases/	false	[]

List Unprotected Branches

The list_unprotected_branches instruction iterates over every branch in a given repo and prints a list of branches that do not have protection rules

Examples:

- action: list_unprotected_branches
  repo_name: jpshrader/github-api-workflows
  include:
    - test
  exclude: 
    - jawn

Argument	Description	Example Value	Required	Default Value
repo_name	the full name of a repo (ex. {owner}/{slug})	jpshrader/github-api-workflows	true	N/A
include	a list of branch names to include (uses string contains to match)	feature/	false	[]
exclude	a list of branch names to ignore (uses string contains to match)	releases/	false	[]

Create Label

The create_label instruction creates a given label across a list of repos. If the label already exists, it will update the existing label with the provided color/description.

Examples:

- action: create_label
  name: example
  color: f29513
  description: 'label for examples'
  repos:
    - jpshrader/github-api-workflows

Argument	Description	Example Value	Required	Default Value
name	the name of the label	example	true	N/A
color	hex color code of the label (not including '#')	f29513	true	N/A
description	description of the label	label for examples	false
repos	list of repos to create the label	jpshrader/github-api-workflows	true	N/A