Categorygithub.com/iomarmochtar/gitlab-token-updater
modulepackage
0.3.0
Repository: https://github.com/iomarmochtar/gitlab-token-updater.git
Documentation: pkg.go.dev

# README

GitLab Access Token Updater/Rotation Manager

This app addresses the following challenges:

  • Token Expiration Management: If you've created numerous Group/Project Access Tokens without expiration dates, these tokens can unexpectedly become a problem once got expired (broken automation, pipeline, etc), as outlined in GitLab's new expiration policy.
  • Premium Solution Limitations: GitLab Premium or Ultimate users are recommended to use Service Account personal access tokens that don’t expire (mentioned in blog above). However, this introduces additional security risks.
  • Service Account Management: Not a direct issue, managing Service Accounts is difficult due to the lack of a UI, as noted in GitLab's current limitations, requiring manual API calls for management.
  • Token Usage Visibility: Tracking Group/Project access token usage is limited, and rotating or renewing tokens requires locating and updating each token’s use, such as in CI/CD or Kubernetes secrets.
  • Response to Token Leaks or Staff Changes: When tokens are leaked or an employee leaves, the lack of visibility or automation around access tokens makes you don't want rotate it.

Installation

Docker

Assuming your main configuration file is located in the current directory:

docker run -v `./config.yml:/tmp/config.yml` -it --rm iomarmochtar/gitlab-token-updater:latest -c /tmp/config.yml

Compiled

Go to the releases page for a compiled version specific to your OS and architecture.

Source Build

Ensure to have following package installed on your local:

Run following commands:

git clone https://github.com/iomarmochtar/gitlab-token-updater.git
cd gitlab-token-updater
make dist-dev

the compiled binary is located under folder dist

How To Use

Preparations

1. Personal Access Token

As Group/Project Access Tokens cannot be used to create other access token related to the access token rotation API (example), use a Personal Access Token for access token rotation.

Create a Personal Access Token with the api scope. You may also create another with the read_api scope for MR dry run purposes.

2. Config File

To run the application, specify the configuration file with the -c or --config argument. Other modes are available.

Execution

For the normal execution, just poin the configuration file with argument -c or --config, some of other modes are available

gitlab-token-updater -c [PATH_TO_CONFIG_FILE]

Mode

You can enable each mode by adding the respective argument, and they can be used in combination.

If any error occurs during execution, it will not interrupt the iteration; errors are accumulated and reported at the end. This behavior can be modified by running in strict mode.

Dry Run

Run with the --dry-run argument. This will execute read-only APIs and verify the existence of specified objects like access tokens and environment variables.

It can be combined with force mode to scan for the existence of each hook. This is recommended during MR validation.

Force

Run with the --force argument to execute the rotation API regardless of the access token's expiry time. This acts as an "emergency button" to ensure all tokens are renewed.

Strict

Run with the --strict argument. Any error encountered during execution will be raised immediately, stopping the process.

Configuration

Consist of YAML formatted content, see the sample one in sample-config.yml, these are the available properties

ParamDescriptionDefaultsRequired
.hostURL of Gitlab instancehttps://gitlab.com/yes
.tokenPersonal access token for GitLab API usage (api scope for all execution, read_api for dry run mode)${GL_RENEWER_TOKEN}yes
.default_hook_retryDefault retry count for hook execution; can be overridden in individual hook configurations0yes
.default_renew_beforeDefault duration to renew an access token before expiry; can be overridden in specific access token configs14dyes
.default_expiry_after_rotateDefault duration for token expiration after rotation3Myes
.manage_tokens[]List of managed access tokenyes
.manage_tokens[].typeType of access token (repository, group, or personal)yes
.manage_tokens[].pathRepository or group locationRequired for repository/group
.manage_tokens[].includeInclude external manage_token configuration, the path is relative to main config fileno
.manage_tokens[].access_tokens[]List of managed access tokensyes
.manage_tokens[].access_tokens[].nameName of access tokenyes
.manage_tokens[].access_tokens[].renew_beforeSpecific renewal period, overriding .default_renew_beforeno
.manage_tokens[].access_tokens[].expiry_after_rotateSpecific expiration period, overriding .default_expiry_after_rotateno
.manage_tokens[].access_tokens[].hooks[]List of actions for each hookno
.manage_tokens[].access_tokens[].hooks[].typeHook type (update_var, exec_cmd, use_token)yes
.manage_tokens[].access_tokens[].hooks[].retryHook retry count, overriding .default_hook_retryno
.manage_tokens[].access_tokens[].hooks[].argsArguments for each hook type (see details below)*some hook type is not required

Notes:

  • .host and .token values can use environment variables in ${THIS_IS_VAR} format.
  • Accepted duration suffixes: d (day), M (month), Y (year).
  • Required arguments for hook types:
    • update_var: .type (repository or group), .path (location), and name (variable name). if .type and .path are not defined, then it will use the same as in it's parent (manage token config).
    • exec_cmd: .path (location of executable) with GL_NEW_TOKEN as injected environment variable for the new token, you can pass another env variables using .env.
    • use_token: not requiring any arguments, it will uses the new token in the current API call; can only be set once as the first hook.

Development

To avoid "polluting" your local environment and to use a consistent development setup, use devcontainer, which is included in this repository and a built in feature in Visual Studio Code.

Misc

Utilizing Service Account

For GitLab Premium or higher, it's recommended to use a Service Account's access token instead of one belonging to an active user. Consider leaving its expiration unset and using a self-update approach, as shown in the examples folder.

Separating Between Access Token For Execution

For more information, refer to this example.

# Packages

Package app main package in executing gitlab access token logic.
No description provided by the author
Package test collections of test helpers.

# Functions

New return command line instance in parsing and executing main instance.

# Variables

BuildHash git commit hash during build process.
CmdName name of command line.
Version app version, this will be injected/modified during compilation time.