Skip to content

Latest commit

 

History

History
141 lines (87 loc) · 10.4 KB

CONFIGURATION.md

File metadata and controls

141 lines (87 loc) · 10.4 KB
Raw

Configuring ld-find-code-refs

ld-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 ld-find-code-refs.

Required arguments

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

Option Description
accessToken LaunchDarkly personal access token with writer-level access, or access to the code-reference-repository custom role resource
dir Path to existing checkout of the git repo. The currently checked out branch will be scanned for code references.
projKey A LaunchDarkly project key. Cannot be used with projects block.
repoName Git repo name. Will be displayed in LaunchDarkly. Repo names must only contain letters, numbers, '.', '_' or '-'.

Command line

Usage:

ld-find-code-refs [flags]

Flags:

  -t, --accessToken string         LaunchDarkly personal access token with write-level access.

      --allowTags                  Enables storing references for tags. The tag will be listed as a branch.

  -U, --baseUri string             LaunchDarkly base URI. (default "https://app.launchdarkly.com")

  -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, LaunchDarkly will attempt to generate links to your VCS service provider per commit. Example: https://github.com/launchdarkly/ld-find-code-refs/commit/${sha}. Allowed template variables: 'branchName', 'sha'. If "commitUrlTemplate" is not provided, but "repoUrl" is provided and "repoType" is not custom, LaunchDarkly will attempt to automatically generate source code links for the given "repoType".
  -C, --contextLines int           The number of context lines to send to LaunchDarkly. If < 0, no source code will be sent to LaunchDarkly. 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 LaunchDarkly 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 LaunchDarkly. Combine with the outDir option to output code references to a CSV.

  -h, --help                       help for ld-find-code-refs

      --hunkUrlTemplate string     If provided, LaunchDarkly will attempt to generate links to  your VCS service provider per code reference.  Example: https://github.com/launchdarkly/ld-find-code-refs/blob/${sha}/${filePath}#L${lineNumber}. Allowed template variables: 'sha', 'filePath', 'lineNumber'. If "hunkUrlTemplate" is not provided, but "repoUrl" is provided and "repoType" is not custom, LaunchDarkly will attempt to automatically generate source code links for the given "repoType".

  -i, --ignoreServiceErrors        If enabled, the scanner will terminate with exit code 0 when the LaunchDarkly API is unreachable or returns an unexpected response.

  -l, --lookback int               Sets the number of git commits to search in history for whether a feature flag was removed from code. May be set to 0 to disabled this feature. Setting this option to a high value will increase search time. (default 10)

  -o, --outDir string              If provided, will output a csv file containing all code references for the project to this directory.

  -p, --projKey string             LaunchDarkly project key. Found under Account Settings -> Projects in the LaunchDarkly dashboard. Cannot be combined with "projects" block in configuration file.

      --prune                      If enabled, branches that are not found in the remote repository will be deleted from LaunchDarkly. (default true)

  -r, --repoName string            Repository name. Will be displayed in LaunchDarkly. Case insensitive. Repository names must only contain letters, numbers, '.', '_' or '-'."

  -T, --repoType string            The repo service provider. Used to correctly categorize repositories in the LaunchDarkly UI. Acceptable values: bitbucket|custom|github|gitlab. (default "custom")

  -u, --repoUrl string             The URL for the repository. If provided and "repoType" is not custom, LaunchDarkly 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.

  -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 ld-find-code-refs

Environment variables

All command line flags are available as environment variables following the "upper snake case" format, with a prefix of LD_. For example, the command line option accessToken may be set as an environment variable e.g. export LD_ACCESS_TOKEN = 'myTestToken'.

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 ld-find-code-refs. The configuration YAML file should be stored as ${dir}/.launchdarkly/coderefs.yaml.

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

projKey: my-project
repoName: my-repo
contextLines: 3

YAML Restrictions

accessToken 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 LaunchDarkly. See ALIASES.md for more information.

Projects

Supported Version: 2.5.0+

Projects allow Code References to scan a monorepo for multiple LaunchDarkly Projects in a single run. If a dir is provided Code References will only start looking for that Project's feature flag keys and aliases below that directory.

Each Project block can support an optional list of alias configuration blocks. Any globally defined aliases will be inherited.

Upgrading note from a version prior to 2.5.0: Previous versions of ld-find-code-refs required projKey parameter to be set. If you want to use 'projects' in your configuration (typically used for monorepos) you will need to remove the projKey parameter.

projects:
    - key: example-project
      dir: subdir/to/start
      aliases:
        - type: camelcase

Delimiters

By default, ld-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 LaunchDarkly.

The following example disables delimiters, and instructs ld-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 launchdarky/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