Skip to content

Latest commit

 

History

History
107 lines (77 loc) · 8.46 KB

CONFIGURATION.md

File metadata and controls

107 lines (77 loc) · 8.46 KB

Configuring bucketeer-find-code-refs

bucketeer-find-code-refs may be configured using command line flags, environment variables, or a YAML file.

If options are defined multiple times across configuration methods, they will be used with the following priority:

flags > env > yaml

In addition, ignore files may be defined to improve performance and exclude files and directories from being scanned by bucketeer-find-code-refs.

Required arguments

The following arguments are required to run bucketeer-find-code-refs. For a detailed description of all options, see the command line arguments

Option Description
apiKey Bucketeer API key with write-level access. Can be specified multiple times for different environments.
dir Path to existing checkout of the git repo. The currently checked out branch will be scanned for code references.
apiEndpoint Bucketeer api service URI.

Command line

Usage:

bucketeer-find-code-refs [flags]

Flags:

      --allowTags                  Enables storing references for tags. The tag will be listed as a branch.
  -U, --apiEndpoint string         Bucketeer base URI.
      --apiKey strings             Bucketeer API key with write-level access. Can be specified multiple times for different environments.
  -b, --branch string              The currently checked out branch. If not provided, branch name will be auto-detected. Provide this option when using CI systems that leave the repository in a detached HEAD state.
      --commitUrlTemplate string   If provided, Bucketeer will attempt to generate links to your VCS service provider per commit. Example: https://github.com/bucketeer/bucketeer-find-code-refs/commit/${sha}. Allowed template variables: 'branchName', 'sha'. If "commitUrlTemplate" is not provided, but "repoUrl" is provided and "repoType" is not custom, Bucketeer will attempt to automatically generate source code links for the given "repoType".
  -C, --contextLines int           The number of context lines to send to Bucketeer. If < 0, no source code will be sent to Bucketeer. If 0, only the lines containing flag references will be sent. If > 0, will send that number of context lines above and below the flag reference. A maximum of 5 context lines may be provided. (default 2)
      --debug                      Enables verbose debug logging
  -B, --defaultBranch string       The default branch. The Bucketeer UI will default to this branch. If not provided, will fallback to 'main'. (default "main")
  -d, --dir string                 Path to existing checkout of the repository.
      --dryRun                     If enabled, the scanner will run without sending code references to Bucketeer. Combine with the outDir option to output code references to a CSV.
  -h, --help                       help for bucketeer-find-code-refs
  -i, --ignoreServiceErrors        If enabled, the scanner will terminate with exit code 0 when the Bucketeer API is unreachable or returns an unexpected response.
  -o, --outDir string              If provided, will output a csv file containing all code references for the project to this directory.
      --prune                      If enabled, branches that are not found in the remote repository will be deleted from Bucketeer. (default true)
  -r, --repoName string            Repository name. Will be displayed in Bucketeer. Case insensitive. Repository names must only contain letters, numbers, '.', '_' or '-'."
  -T, --repoType string            The repo service provider. Used to correctly categorize repositories in the Bucketeer UI. Acceptable values: bitbucket|custom|github|gitlab. (default "custom")
  -u, --repoUrl string             The URL for the repository. If provided and "repoType" is not custom, Bucketeer will attempt to automatically generate source code links for the given "repoType".
  -R, --revision string            Use this option to scan non-git codebases. The current revision of the repository to be scanned. If set, the version string for the scanned repository will not be inferred, and branch garbage collection will be disabled. The "branch" option is required when "revision" is set.
      --subdirectory string        If the .bucketeer/coderefs.yaml file is not in the root of the repository, provide the path to the subdirectory containing the configuration, relative to the root. Code references will only run on this provided subdirectory. This allows a monorepo to have multiple configuration files, one per subdirectory.
  -s, --updateSequenceId int       An integer representing the order number of code reference updates. Used to version updates across concurrent executions of the flag finder. If not provided, data will always be updated. If provided, data will only be updated if the existing "updateSequenceId" is less than the new "updateSequenceId". Examples: the time a "git push" was initiated, CI build number, the current unix timestamp. (default -1)
      --userAgent string           (Internal) Platform where code references is run.
  -v, --version                    version for bucketeer-find-code-refs

Environment variables

All command line flags are available as environment variables following the "upper snake case" format, with a prefix of BUCKETEER_. For example, the command line option apiKey may be set as an environment variable e.g. export BUCKETEER_APIKEY = 'myTestToken'. For multiple API keys, you can use comma-separated values: export BUCKETEER_APIKEY = 'key1,key2,key3'.

YAML

A YAML file may be used to specify most command line arguments, as well as a number of additional options for advanced usage of bucketeer-find-code-refs. The configuration YAML file should be stored as ${dir}/.bucketeer/coderefs.yaml.

Command line options translate directly to keys in your YAML file. For example, the following options can be specified in YAML as follows:

contextLines: 3
debug: true
outDir: 
dryRun: false
repoOwner: 
repoName: 
repoType:

YAML Restrictions

apiKey and dir may not be specified in the YAML file, and must be specified as either command line flags or environment variables.

Advanced YAML configuration

In addition to all command line options, the coderefs.yaml file allows you to configure Code Reference Aliases, Projects, and custom flag key delimiters.

Aliases

Patterns to match aliases for your flag keys may be defined to better suit your implementation of Bucketeer. See ALIASES.md for more information.

Projects

Delimiters

By default, bucketeer-find-code-refs will only match flag keys surrounded by single quotes ('), double quotes ("), or backticks (`). This default behavior may be disabled and additional delimiters may be defined to better suit your implementation of Bucketeer.

The following example disables delimiters, and instructs bucketeer-find-code-refs to only match flag keys surrounded by carets (< and >)

delimiters:
  disableDefaults: true # boolean. if enabled, only `additional` delimiters will be used.
  additional:           # an array of single-character strings
    - '<'
    - '>'

Ignoring files and directories

All dotfiles and patterns in .gitignore and .ignore will be excluded by default, except the .github directory. Flags may be referenced when using bucketeer/gha-flags. If you would like to skip scanning these files, add .github to one of the ignore files.

To ignore additional files and directories, provide a .ldignore file in the root directory of your Git repository. All patterns specified in .ldignore file will be excluded by the scanner. Patterns must follow the .gitignore format as specified here: https://git-scm.com/docs/gitignore#_pattern_format