Administration Support IssueOps

This repository contains automation that allows the support team of an organization to use IssueOps to request temporary elevation of their access to perform tasks that require administrative permission. All the operations done during the process are reported as part of the audit log of the user. Closing the issue removes the permission.

v2 Migration

There are a number of major changes in the v2 release of this action. Specifically:

• The CLI component has been removed in favor of using the @github/local-action utility
• The action is now using Node.js v20
• The action inputs have been updated to not require multiple runs to parse and then invoke the correct command

When migrating, please refer to the example workflows for the correct usage of the action.

Setup

To use this action in your own organization(s), follow the below steps:

1. Create a Personal Access Token (PAT) with admin:org and repo write permissions

   [!NOTE]

   It is highly recommended to use a machine user for this purpose, not a personal account.

2. Clone this repository into your organization

3. In your cloned repository, create a GitHub Actions secret named PAT using the token you created previously

4. Move the following workflow files from the .github/workflow-examples/ directory to the .github/workflows/ directory:

   • check-workflow.yml
   • demotion-workflow.yml
   • promotion-workflow.yml

5. Update the DEMOTION_ERROR_NOTIFY environment variable in the following workflow files:

   • demotion-workflow.yml

6. Update the ALLOWED_ORGS environment variable in the following workflow files:

   • check-workflow.yml
   • demotion-workflow.yml
   • promotion-workflow.yml

   This should be see to a comma-separated list of the organizations where you want to allow to use this automation (and the PAT you created can acess)

   env:
     ALLOWED_ORGS: 'octo-org,octo-org2'

7. Commit and push the changes to your repository

8. Enable GitHub Actions in the repository

   As this automation provides admin access to organizations, you may only want certain teams to be able to fill issues in.

9. Enable repositorty rulesets so only certain users can access the repository

10. Grant read permission to any users or teams who will need to be able to create issues in the repository

11. Set the repository visibility to private, not internal

Automation

To request the permission:

1. Open an issue using the template provided in this repository

   Field	Description
   Organization	Organization where you want to be promoted
   Description	Expanation of why this request is being submitted
   Ticket	ID of a related ticket in your support system
   Duration	Duration in hours that you need the permission

   The completed form will look like the following:

   ### Organization
   
   octo-org
   
   ### Description
   
   A user requires to be added to a team and nobody else can give him access
   
   ### Ticket
   
   1234
   
   ### Duration
   
   1

2. Once the issue is created, a GitHub Actions workflow will trigger providing you with temporary access to perform your task(s)

3. Once you have completed your task(s), close the issue to revoke your access automatically

4. All the actions performed as an admin will be audited and added to the repository, so be cautious of the changes done in the organization

Important

The duration requested will be approximate and has a ~1h error. We recommend to close the issue when the task is completed.

Development

CLI Usage

The @github/local-action utility can be used to test your action locally. It is a simple command-line tool that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run your action locally without having to commit and push your changes to a repository.

The local-action utility can be run in the following ways:

• Visual Studio Code Debugger

  Make sure to review and, if needed, update .vscode/launch.json

• Terminal/Command Prompt

  cd admin-support-cli
  
  # npx local-action <action-yaml-path> <entrypoint> <dotenv-file>
  npx local-action . src/main.ts .env

You can provide a .env file to the local-action CLI to set environment variables used by the GitHub Actions Toolkit. For example, setting inputs and event payload data used by your action. For more information, see the example file, .env.example, and the GitHub Actions Documentation.

Additionally, this local-action CLI can make use of mock webhook payloads. You can provide a JSON file path for the GITHUB_EVENT_PATH environment variable in the .env file. For a minimal example that can be used with this action, see issue_payload.example.json.